Open-Xchange - User contributions [en]

SourceCodeAccess

2025-03-27T10:09:49Z

Choeger:

= How to download the Open-Xchange source code =

Starting with 6.22 the source code of Open-Xchange server is available from Git repositories.

The following repositories exist:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Repository
! content
|-
| https://gitlab.open-xchange.com/oss/appsuite/core/middleware
| The main repository containing most of the parts of Open-Xchange server
|-
| https://gitlab.open-xchange.com/frontend/core
| The user interface of OX App Suite
|-
| https://gitlab.open-xchange.com/appsuite/guard
| The server-code and UI for OX Guard (PGP implementation)
|-
| https://code.open-xchange.com/git/frontend6
| The AJAX user interface (version 6)
|-
| documentconverter-api
| The API of the server-based part of the documentconverter needed for OX Text
|-
| office
| The server-code for OX Text and OX Spreadsheet
|-
| office-web
| The frontend-code for OX Text and OX Spreadsheet
|-
| mobile-api-facade
|
|-
|}

== Git operations to access the code ==

To clone a repository in case of gitlab please follow the instructions shown there.
For cloning from code.open-xchange.com, run

$ git clone https://code.open-xchange.com/git/<repository>
$ cd <repository>
$ git checkout -t origin/<branch>

== The currently used Git branches ==

For a list of available branches, run

$ git branch -r

The main development process uses the following branches:

{| border="1" cellspacing="0" cellpadding="5" align="center"
! Git branch
! content
|-
| develop
| head development
|-
| release-<version>
| stabilizing for <version> release
|-
| master
| maintenance of current release
|-
| master-<version>
| maintenance of previous releases
|-
|}

[[Category: OX6]]
[[Category: AppSuite]]
[[Category: Developer]]

OX as a Service Provisioning using SOAP

2023-03-02T12:18:35Z

Choeger: /* Generating the SOAP client */

= Tutorial: Provision OX as a Service using SOAP =

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html
; about dialogue: com.openexchange.appsuite.servercontact, see below

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
},
{
'value' => 'My Example Org | <a href=\\"https://www.example.org\\" target=\\"_blank\\">www.example.org</a> | <a href=\\"https://example.org/help\\" target=\\"_blank\\">Contact us</a>',
'key' => 'com.openexchange.appsuite.servercontact'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

'''Note that the below instructions only work with Java version 8 and no later version'''

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">

package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.Entry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final long unifiedQuotaMax = 1000l;

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");
auser.setMaxQuota(unifiedQuotaMax);

// enable unified quota (might be enabled globally, already, though)
final Entry unifiedQuota = new Entry();
unifiedQuota.setKey("com.openexchange.unifiedquota.enabled");
unifiedQuota.setValue("true");

final SOAPStringMap configEntries = new SOAPStringMap();
configEntries.getEntries().add(unifiedQuota);

final SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
config.setValue(configEntries);

final SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(config);
auser.setUserAttributes(userattrs);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), unifiedQuotaMax, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if (oxaasport.existsLogin("auser", oxaasAdminCreds)) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2023-02-07T13:54:45Z

Choeger:

= Tutorial: Provision OX as a Service using SOAP =

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html
; about dialogue: com.openexchange.appsuite.servercontact, see below

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
},
{
'value' => 'My Example Org | <a href=\\"https://www.example.org\\" target=\\"_blank\\">www.example.org</a> | <a href=\\"https://example.org/help\\" target=\\"_blank\\">Contact us</a>',
'key' => 'com.openexchange.appsuite.servercontact'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">

package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.Entry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final long unifiedQuotaMax = 1000l;

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");
auser.setMaxQuota(unifiedQuotaMax);

// enable unified quota (might be enabled globally, already, though)
final Entry unifiedQuota = new Entry();
unifiedQuota.setKey("com.openexchange.unifiedquota.enabled");
unifiedQuota.setValue("true");

final SOAPStringMap configEntries = new SOAPStringMap();
configEntries.getEntries().add(unifiedQuota);

final SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
config.setValue(configEntries);

final SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(config);
auser.setUserAttributes(userattrs);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), unifiedQuotaMax, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if (oxaasport.existsLogin("auser", oxaasAdminCreds)) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2023-02-07T13:53:18Z

Choeger:

= Tutorial: Provision OX as a Service using SOAP =

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html
; about dialogue: com.openexchange.appsuite.servercontact, see below

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
},
{
'value' => 'My Example Org | <a href=\\"https://www.example.org\\" target=\\"_blank\\">www.example.org</a> | <a href=\\"https://example.org/help\\" target=\\"_blank\\">Contact us</a>',
'key' => 'com.openexchange.appsuite.servercontact'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">

package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.Entry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final long unifiedQuotaMax = 1000l;

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");
auser.setMaxQuota(unifiedQuotaMax);

// enable unified quota (might be enabled globally, already, though)
final Entry unifiedQuota = new Entry();
unifiedQuota.setKey("com.openexchange.unifiedquota.enabled");
unifiedQuota.setValue("true");

final SOAPStringMap configEntries = new SOAPStringMap();
configEntries.getEntries().add(unifiedQuota);

final SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
config.setValue(configEntries);

final SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(config);
auser.setUserAttributes(userattrs);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), unifiedQuotaMax, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if (oxaasport.existsLogin("auser", oxaasAdminCreds)) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

Login variations

2022-06-02T13:43:43Z

Choeger: /* Token Login */

<div class="title">Login variations</div>

'''Introduction:''' This paper describes Open-Xchanges's authentication and session handling. It gives an overview of all available mechanisms and on how to safely pass on sessions from external applications to the Open-Xchange Server (Single Sign On, SSO).

== Overview ==
The Open-Xchange Server web front-end is implemented in AJAX (Asynchronous JavaScript and XML). Thus the complete user interface (GUI) is running in a browser. Opposed to standard web applications there are no HTML pages generated and delivered by the browser.

The complete user front-end is rendered and displayed in the browser. Based on HTTP/S the data are exchanged with the server via JavaScript Object Notation (JSON). That means it is not possible to simulate front-end actions via HTTP/S request by simulating respectively formatted GET/POST calls. Instead, another abstraction is taking place that exclusively transfers data from GUI to server and vice versa.

The Open-Xchange Server includes a session daemon (sessiond) that keeps the current data of a logged in user. If successfully authenticated the information kept in the session are sufficient for accessing the Open-Xchange Server.

==Access to IMAP Back-End services==
To access external E-Mail systems (IMAP/SMTP) the Open-Xchange Server has to know the credentials of the current user for the system, i. e. the session object has to keep the respective password for the access in plain text. That means authenticating via SessionIDs alone is not sufficient. Authentication always has to take place by entering the username and password.

(There are two exceptions: either if one master password is used for all IMAP accounts, or if a very special implementation of MAL is used, which does not need a password.)

==Basic Implementation Rules==
* It must not be possible to get a valid session by e. g. guessing a SessionID. This is especially important when being passed on by an external system
* A session must not be verified by a single SessionID only, but has to compare at least two different data types, this is what the Session-Secret is for
* Both SessionID and Session-Secret must never be passed from the Open-Xchange server to the client in the same request. This ensures, that potential issues in the stack between the client and Open-Xchange (proxies, caches, loadbalancer, Apache, …) can not lead to wrong sessions
* To enhance security Session-Secret and SessionID are transferred as different data types. The Session-Secret will always be transferred as a cookie, the SessionID will be transferred as URL parameter if persistent auto-login is not activated for this session.
* It must never be possible to have conflicting session information per client (multiple cookies) within the same cookie store
* If any error in the session handling is detected, the relevant request is discarded and logged. It is not tried to fix the issue
* In memory data (SessionID) of the browser GUI must never be changed during a valid session
* All relevant information regarding session management must always be written to the relevant logfiles
* The whole mechanism is only secure when being used via encrypted connection
* ATTENTION: If persistent autologin is activated for the system and a user decided to use it, all information necessary to access the Open-Xchange server is stored within the browsers cookie store.  This means, that the security of the whole system depends on the level of security of the browsers cookie store

== Authentication and Session Tokens ==
Following tokens are used for the session management:

=== SessionID ===
The SessionID is used to identify every session. It is a UUID, generated by the backend via default Java UUID implementation. It is written into the OX logfiles for every log message. When no auto-login is used for the session, then the SessionID is transferred as an URL parameter. If auto-login is activated, then the SessionID is transferred as a cookie.

=== Session-Secret ===
The Session-Secret is used to verify every session. It is a UUID, generated by the backend via default Java UUID implementation. Only accesses, where the Session-Secret matches with the one stored in SessionD for the given SessionID are valid. Mismatches lead to immediate session termination.

=== Public Session ===
The public Session is used as a replacement for the SessionID. It is a UUID, generated by the backend via default Java UUID implementation. The Public Session is transferred as a cookie named <tt>open-xchange-public-session-uuid</tt>. Using the Public Session is limited to some non critical requests. By using this cookie instead of a request parameter, the browser is able to cache the response of special requests (e.g. contact images).

=== Random ===
The Random-Token is a one time token with a limited lifetime, which is used to initiate sessions through 3rd party applications or websites. It is a UUID, generated by the backend via default Java UUID implementation. This token is deprecated and subject to change.

=== Cookie Handling ===
In several situations, cookies are used to store and transfer the session tokens. The following rules for cookie creation and storage apply.

==== Only one cookie per client session type ====
It must never happen, that the same client has more than one session associated with an Open-Xchange server. Therefore the cookies need to have the same name. If a new cookie is set to the browser, the original one will be overwritten. With the next client access either the SessionID or the Session-Secret do not match anymore and the invalid session is terminated.
Multiple clients with same cookie store.

On the other hand it may happen, that several clients use the same cookie store. E.g. a standard browser GUI session and a browser plugin session. Therefore the cookie name needs to contain informations about the client.

==== Naming of cookies ====
The cookies are named following this schema:

open-xchange-session-<<name token>>=<<SessionID>>
open-xchange-secret-<<name token>>=<<Session-Secret>>

Where <<name token>> is generated from configurable data associated with the client. It is a md5-hash build from the client-id and the User-Agent is used to identify the client. Other parameters can be added through a configuration file. If a request is performed by a browser with an invalid hash the corresponding cookies and session are invalidated.

====Lifetime of cookies====
Normally, cookies are session cookies, which get invalid/deleted when the browser is shut down.
Using the persistent auto-login, the cookies are persistent cookies, with a configurable default. The default lifetime is one week.

====Security of a cookie====
Cookies can be configured in different ways to be secure. For further information visit [[OXSessionSecurityFeatures]]

All cookies get deleted when a logout is performed.

==IP Check==
Per default an IP check is activated to terminate every session immediately, if the IP address of the client changes during the session lifetime. This check is not processed, when a session is reactivated following the persistent auto-login process.
There are several configuration options to enable, disable the IP Check and to define IP Ranges to omit the check and/or accept recurring connections from within these ranges. For further information on the configuration see [https://oxpedia.org/wiki/index.php?title=AppSuite:Configuration_properties_7.8.2 configuration properties].

==Access via web browser with user credentials==
When directly logging in to the system by entering the credentials, following steps will be done to authenticate the user or verify the validity of the session after the authentication:

# The browser sends initial request to the Open-Xchange server. The client represented by the application:
## is not authenticated yet
## has no cookie
## has no session ID.
# Open-Xchange server sends an AJAX application to browser. The application is loaded into the browser and no data is exchanged between server and application.
# The AJAX application then will try to do an auto-login. Because the application has no knowledge of the cookies that may already be stored in the browser it will try to login the client. For further information on auto-login see [[OXSessionAutologin]]. With the precondition form 1. the auto-login try will be denied.
# The user enters username and password in the front-end.
# The username and password are sent to the server via JSON (SSL). If the user activated persistent auto-login on the login screen, this information is passed with the same request.
# The server authenticates the client and sends following data back to the browser via JSON (the data are saved in the session object):
## Session ID via JSON object
## (Optional) Random token for initial login via JSON object. For the random token to be send the server needs to be configured(see login.properties – com.openexchange.axaj.login.randomToken). CAUTION! The random token is deprecated and should no longer be used!
## Cookie with JSESSIONID. The JSESSIONID is set for loadbalancing to the browser
## Cookie containing the session secret. If persistent auto-login is selected, the cookie is configured with the relevant type and validity.
## Cookie containing the public identifier.
# The AJAX front-end saves the session ID in its memory. (Optional) Ignores the random token.
# If the persistent auto-login is enabled the AJAX front-end will send a store request. If no error occurs a configured cookie with the relevant type and validity containing the session ID is set to the browser.
# The AJAX front-end sends initial data request via JSON to the Open-Xchange server and provides the session ID as an URL parameter. The secret is send along as a cookie.
# The Open-Xchange server processes this data request and compares:
## Session ID for validity in sessiond
## Session-Secret from the cookie for validity with session
# The request is correctly authenticated and is answered by the server.
# (Optional) Random token is discarded after timeout from sessiond.
# Repeat 9. - 11. until end of session

If the user does not use the persistent auto-login, the session is only valid as long as the browser is opened. It will be cleared either on logout, on browser termination or with any occurring error.

For any details on the requests and responses please visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

==Access via web browser after authentication with external system==
The goal is to authenticate in the Open-Xchange system through an external system and to safely pass on the received session data to a browser. To do so the external system has to know the user data (username, password) in plain text.

The process is based on the session initialization in the Open-Xchange Server via the JSON interface and on passing on the received data to a browser. The browser finally initializes the session with an additional random token that is only valid for one single access.
# External tool sends initial JSON request directly to Open-Xchange Server
## not authenticated yet
## no cookie
## no SessionID
# The Open-Xchange Server authenticates and delivers back following data to external tool via JSON (all the data are stored in the session object in sessiond)
## SessionID in JSON object
## Random token for initial login via JSON object (required for SSO login)
## Cookie with Session-Secret is not set
# External tool starts browser with special URL, that contains at least following data:
## Random token for initial login
# Open-Xchange Server compares:
## Random token for validity in sessiond
# Open-Xchange Server sends to the browser:
## SessionID in JSON object
## Cookie with JSESSIONID for loadbalancing is set to the browser
# The second part of the tokens is delivered in a separate request
## Cookie with Session-Secret is set to the browser If persistent auto-login is selected, the cookie is configured with the relevant type and validity
# Open-Xchange removes random token from sessiond.

Then the process continues as described in the section above. The session is then verified with the SessionID and Session-Secret.

==Token Login==
A dedicated login action (tokenLogin) is used to acquire a server token bound to a given client token. The combination of these tokens allows another client to gain a valid session. This Login is intended to replace the random token login. With this method there is no request or response containing all necessary information to create a valid session.

An example how to use this method to implement an external interactive login page using XHR can be found [[Tokenlogin_form|here]]

See also the [https://documentation.open-xchange.com/components/middleware/http/7.10.6/index.html#!Login/doTokenLogin corresponding documentation in the OX HTTP API.]

==Form Login==
The Form Login provides a simple way of accessing the web frontend just by using standard HTML forms. The response contains a redirect link to the Web-UI. See [[OXSessionFormLogin]] for details.

==Redeem Token Login==
With a valid session it is possible to acquire a secret. Using this secret another system is able to generate a valid session.
This session may also contain the users password (configurable). The system in question needs to be registered at the server and has to identify itself with a key configured at the open-xchange server. This is only for internal communication and by default no keys are available.

== Authentication against other services ==
OX6 and AppSuite allow authentication using other services, too. This is not in the scope of this article. The Services team is available to build plugins for such services. Some standard ones are already implemented, see the following articles for that:
* [[Authentication IMAP Plugin description]]

For further information on the session see [[OXSessionLifecycle]].

For further information on HTTP API visit the [https://documentation.open-xchange.com/latest/middleware/http-api-gen/#_login_resource Technical Documentation]

[[Category:Server]]
[[Category:OX6]]
[[Category:AppSuite]]
[[Category:Auth]]

AppSuite:File Storages per User

2022-04-14T11:26:34Z

Choeger: /* When is a user filestore enabled or when did a user has a own filestore? */

{{Version|7.8.0}}

= File Storages per user =

This document tries to outline and explain the new concept of having the possibility to specify file storages on a per user basis that is introduced with Open‐Xchange Server v7.8.0.

== The previous situation ==

Before the introduction of the file storages per user feature, it was only possible to specify the file storage association per context.
That file storage was used for all modules/functions that are supposed to store/retrieve files:
* Drive
* Thumbnails
* PIM attachments
* Signature attachments

File storages are registered and maintained in file store table held in configDb database. File storage obtains a unique identifier, a base URI and a size limitation.

For each context a file storage identifier is specified alongside with a context quota that defines how much space that context is allowed to occupy in assigned file storage. Thus the sum of all quotas from those contexts assigned to file storage must not exceed the file storage’s size.

[[Image:file_storage_picture1.png|One file storage per context|650px]]

== Motivation ==

The motivation is to differentiate between file storages for common context‐associated files and Drive file. Those Drive files may further reside in the common context‐associated storage, but it also possible to specify user‐associated file storages where Drive files are maintained. The association is determined based on a folder's creator/owner: The quota gets accounted to that user that created a folder (provided the user has a user‐associated file storage).

[[Image:file_storage_picture2.png|Differentiate|650px]]

That kind of separation allows different provisioning scenarios that an administrator possibly wants to achieve. With regard to Drive files it is now possible to define per context that:

* All Drive files reside in the file storage associated with the context, which is either automatically determined or explicitly set (through -F,--destination-store-id option) when creating a context. All Drive files (from users of that context) and all other file resources (Snippets, PIM attachments, ...) share the same quota usage and limit settings. The file storage associated with the context is called '''context file storage'''.
* Certain users are supposed to store their Drive files in their own file storage with individual quota settings different from the context file storage. All files created in Drive folders owned by such a user are then accounted to that user-associated file storage having their own quota usage and limitation. The user-associated file storage may be set on user creation as it is for context creation. The file storage associated with a user is called '''user file storage'''. Introducing a user file storage is suitable when an administrator wants to have user-sensitive quota settings for Drive files and/or wants to assign a different type of storage for Drive files uploaded by users; e.g. let seldom used/accessed file resources reside in context file storage, but let frequently, highly accessed Drive files reside in a better storage sink
* A certain user has his own (bigger) file storage for Drive files and other users of that context are supposed to use that file storage to share the quota usage and limitation specified for that file storage. A file storage owned by a user that is also used by other users is called '''master file storage'''.

Having that possibilities of separation for quota usage and limitation it is possible to apply a certain use case scenario to contexts; e.g.

* Slow mass storage vs. fast Drive storage setup
* OX Drive Stand‐Alone setup

When assigning dedicated file storage for Drive to a certain user, the user’s file occupation is no more accounted to the overall context in which that user resides, but gets accounted to a dedicated user quota. Such a user quota can be used for different sales strategies that include tracking the user’s file occupation.

To achieve the file storage association on a per user basis, the existing user table has been enhanced by file storage and quota information as it is for the context table. Moreover the filestore_usage table has also been enhanced by the capability to account storage occupation to a certain user

[[Image:file_storage_picture3.png|Enhancements|650px]]

In addition the user table has also been extended by filestore_owner column. That column is used to let a user’s file storage be combined with another user’s storage. This serves the scenario in which a grouped OX Drive Stand‐Alone setup is operated. Multiple users’ file occupation gets accounted to a master user account.

Furthermore Open‐Xchange allows changing the running setups at any time to adjust the file storage usages/associations according to possibly changing needs/requirements.

=== Note ===

Please note that with introducing the concept of having user-associated file storages, the output for "listfilestore" command-line tool changed. Since also a user can be accounted to a file storage's capacity, the output changed to be:

/opt/open-xchange/sbin/listfilestore -A oxadminmaster -P secret
id path size reserved used max-entities cur-entities
2 file:///var/opt/filestore 1000 300 0 5000 2

Hence, "maxctx" is replaced with "max-entities" and "curctx" is replaced with "cur-entities"

== Seamless integration and flexibility ==
The new more flexible approach fits seamlessly into existing context/file storage setups. Thus there is no need to change anything, unless demanded by administrator

=== The fall‐back setup ===

[[Image:file_storage_picture4.png|The fall-back setup|650px]]

Everything stays as is. There is a storage‐per‐context association and every file is held in that storage. There are no user‐specific file storage attributes set in user table.

=== Slow mass storage vs. fast file storage setup ===

[[Image:file_storage_picture5.png|Slow mass storage|650px]]

There are two storages available: a file‐based and an S3 storage (assuming that the S3 one would be faster). While the context has the file‐based storage set, users in that context do have individual name spaces in the S3 storage.

That way common files (PIM/Signature attachments, thumbnails) are stored to context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage. Every user is allowed to occupy up to 10GB of space in the S3 storage (this can be varied as well).

=== OX Drive Stand‐Alone – Single User ===

[[Image:file_storage_picture6.png|OX Drive Stand-Alone - Single User|650px]]

Again there two file storages. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

Context designated to the Single User scenario for OX Drive Stand‐Alone operation, do hold only one user that has its individual name space associated in the S3 storage.

Again common files (PIM/Signature attachments, thumbnails) are stored in the context‐ associated file‐based storage while Drive documents are stored in the individual user name spaces in the S3 storage of each context. Every Drive document accounts the user‐sensitive quota of the associated user.

=== OX Drive Stand‐Alone – Business Account ===

[[Image:file_storage_picture7.png|OX Drive Stand-Alone - Business Account|650px]]

There two different file storages as in the previous setups. Again the file‐based one is assumed to serve the slow mass storage behavior while S3 is assumed to be the fast storage.

For this setup users do not hold their own individual name space in the S3 storage, but all share the same name space of the master user in the S3 storage. Moreover there are no dedicated user quotas, but all Drive documents do account to the master user’s quota

== Extensions to provisioning command‐line tools ==

=== createuser ===

The existing createuser CLI is enhanced by the following options
‐q/‐‐quota The file storage quota in MB for associated user
‐f/‐‐filestore The identifier for the file storage.
‐o/‐‐owner The owner for the file storage. If no owner is given and f/filestore option is set, the user itself is taken as owner

=== changeuser ===

The existing changeuser CLI is enhanced by the following option
‐q/‐‐quota The file storage quota in MB for associated user

'''Note:''' Option ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET in file 'AdminUser.properties' controls if a user file storage is automatically enabled if the ‐q/‐‐quota option is given on a 'changeuser' invocation as an alternative to 'movecontextfilestore2user'. For users without a user file storage the 'changeuser' CLT needs to be called with a quota value different to unlimited (-1) and unlimited quota will only be enabled in case the user already has a user file storage.

=== movecontextfilestore2user ===

Move a user’s files from a context to an individual storage name space. 
Usage: movecontextfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another which means that at least one of them must be set.

=== moveuserfilestore2context ===

The counterpart for the previous CLI. Move a user's files from his individual storage name space to the context storage name space. 
Usage: moveuserfilestore2context

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another that means that at least one of them must be set.

=== moveuserfilestore2master ===
Move a user's files from his individual storage name space to the storage name space of specified master. 
Usage: moveuserfilestore2master

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== movemasterfilestore2user ===
Move a user's files from a master account name space to an individual storage name space. 
Usage: movemasterfilestore2user

‐h,‐‐help Prints a help text
‐‐environment Show info about commandline environment
‐‐nonl Remove all newlines (\n) from output
‐i,‐‐userid <userid> | Id of the user
‐u,‐‐username <username> | Username of the user
‐A,‐‐adminuser <adminuser> ? Admin username
‐P,‐‐adminpass <adminpass> ? Admin password
‐c,‐‐contextid <contextid> | The id of the context
‐N,‐‐contextname <contextname> | context name
‐m,‐‐master <master> Master user id. If not set, the context administrator is assumed to be the master user.
‐f,‐‐filestore <filestore> * The identifier for the file storage.
‐q,‐‐quota <quota> * The file storage quota in MB for associated user.

Entries marked with an asterisk (*) are mandatory.
Entries marked with an question mark (?) are mandatory depending on your configuration.
Entries marked with a pipe (|) are mandatory for one another, which means that at least one of them, must be set.

=== Creating a user file storage ===

Having the extensions to command-line tools a user-associated file storage can be enabled:

* After using 'movecontextfilestore2user' command-line tool
* Using 'changeuser' command-line tool with quota and filestore options or only quota options and "ALLOW_CHANGING_QUOTA_IF_NO_FILESTORE_SET" set to "true" in 'AdminUser.properties' file
* By provisioning via 'createuser' command-line tool with quota and filestore options

== Useful command‐line tools ==

The following command‐line tools might be useful to get an overview

* 'listfilestore' to list available file storages that can be assigned to contexts/users
* 'listcontext' to get the quota limit specified per context or -1 if none
* 'listuser' to get the quota limit specified per user or -1 if none
* 'listuserfilestores' to get a listing of users that use their own user file storage

== FAQs ==

=== When is a user filestore enabled or when does a user have an own filestore? ===

A user filestore has an own filestore if a filestore is assigned to this user. This can either be done via the create and update clt's or via the movecontextfilestore2user clt.

=== When is which quota affected? ===

In case the user has no own filestore the quota of the context filestore is affected. In case the user has an own filestore or in case the user is a slave user of another users filestore the quota of this user filestore is affected.

=== How can a user check his quota usage? ===

The 'Quota' portal widget shows quota and usage.

=== How to change the filestore quota shown in the portal widget? ===

To change the quota one just has to use the changeuser or changecontext CLT with the --quota (-q) argument. E.g.:

changecontext -A adminmaster -P masterpassword -c -q 1024

=== How does quota work for public files? ===

The quota of the folder creator/owner is in charge for files other users put inside. This affects the quota for users having an own filestore

=== What happens with ownership of public files and folders when the creator/owner gets deleted? ===

This depends which argument is used during the delete operation. In the default case, the context admin is assigned as the owner. But it is also possible that the data is assigned to a different user or that the data is completed removed.

=== What happens in over quota scenarios by deleting users? ===

If the data is assigned to a different user the quota limit is ignored. But the user (inheriting deleted user's files) is supposed to clean existing files as any attempt to create a Drive file will fail due to over-quota

=== How to deal with quota issues for the context admin caused by public files? ===

If the quota is too limited for the context admin the data should be completely removed or assigned to a different user. E.g.:
deleteuser -A ctxadmin -P password -c -i --no-reassign

AppSuite:CrossContextDatabase

2021-11-05T07:54:05Z

Choeger:

<div class="title">Cross-context database</div>

{{VersionFrom|7.8.0}}

This article is valid from 7.8.0 to 7.10.1 and is not updated for newer versions anymore. For 7.10.2 and onwards you can find the corresponding documentation at https://documentation.open-xchange.com (currently https://documentation.open-xchange.com/latest/middleware/administration/global_database.html)

__TOC__

For storing data across context boundaries, a so called "global" database is used by the server. For example, such shared data could be information about guest users or data for registered OAuth applications. This article gives an overview about the basic concepts and how to setup a global database.

== Register databases ==

As a prerequisite, a global database needs to be registered in the Open-Xchange server's configuration database. At the storage layer, global databases are handled just like the ordinary <tt>context</tt> databases storing all the existing groupware data. Therefore, the same underlying technologies can be used for replication like master/slave- or Galera-based setups, as well as registering additional database pools for sharding in very large installations.

So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:

$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal --hostname localhost --dbuser openexchange --dbpasswd db_password --master true --maxunit 0
database 8 registered

Remember the returned database identifier, <tt>8</tt> in the above example, we'll need it at a later stage.

Optionally, in case a database slave should be added, you can register it afterwards by specifying the database identifier as <tt>masterid</tt> like follows:

$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal_slave --hostname slave_host --dbuser openexchange --dbpasswd db_password --master false --maxunit 0 --masterid=8
database 9 registered

For smaller or test environments, it's also possible to re-use a previously registered groupware database for cross-context data, i.e. any database marked as <tt>master</tt> by the <tt>listdatabase</tt> utility may be used. Please note that all cross-context data is not accounted when calculating the database weight during context creation.

== Context Groups ==

As already mentioned, data inside the global database is shared between and available to all contexts in the installation. For setups serving multiple different "brands" or "domains", this may not be the desired behavior, so that an additional level of data separation is needed for cross-context data. Therefore, one or more contexts can be classified into a specific "group". The association with the group is done by assigning the property <tt>com.openexchange.context.group</tt> to a context via config cascade. A context may only be part of one group, contexts without group association automatically fall into the "default" group.

Please note that context group names must not be longer than 32 characters!

As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:

$ /opt/open-xchange/sbin/createcontext [...] --config/com.openexchange.context.group=clever_hosting

Or, if you already tagged your contexts with different taxonomy types (like <tt>clever</tt> and <tt>smart</tt> in our example), the assignment to a context group can also be achieved at "ContextSet" level inside an <tt>.yml</tt>-file of your <tt>contextSets</tt> definitions:

<pre>
clever_group:
withTags: clever
com.openexchange.context.group: clever_hosting
ui/product/name: "Clever Hosting"
[...]

smart_group:
withTags: smart
com.openexchange.context.group: smart_hosting
ui/product/name: "Smart Hosting"
[...]
</pre>

In the global database, the context group identifier serves as differentiating key for various data. For example, data of a guest user that was invited to a share in one context of a group can be used throughout all other contexts of the same group. Or, there may be a different set of registered OAuth applications available for each context group. Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. The next chapter describes the global database configuration file in more detail.

== Configure databases ==

Global databases are defined in the configuration file <tt>globaldb.yml</tt>. It mainly serves the purpose to map registered global databases to context groups. In case no advanced context grouping is necessary, e.g. because there's only a single brand in the installation, it's sufficient to supply the identifier of the previously registered master database, see [[#Register databases|Register databases]] above, inside the <tt>default</tt> section of the configuration file. For example, if the identifier of the global database master is <tt>8</tt>, the section would look like:

<pre>
default:
groups: [default]
id: 8
</pre>

This would lead to all cross-context data being stored at this database, assigning distinguished context groups as described in [[#Context Groups|Context Groups]] is not required.

If there are multiple context groups, those can be directed to a specific global database by adding their names to the <tt>groups</tt> property of a configuration section. For example, if the groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> should use database <tt>8</tt>, too, one could define:

<pre>
default:
groups: [default,smart_hosting,clever_hosting]
id: 8
</pre>

Removing the default group name <tt>default</tt> from the groups list is not recommended, and should only be done if you can ensure that each context of the installation has it's group assignment defined correctly in the property <tt>com.openexchange.context.group</tt>.

Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. Since context groups are bound to a configuration section by specifying the group name in the "groups" array, and each configuration section may target another global database, in theory there could be as much global databases as there are defined context groups. For example, to enforce data from the context groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> being stored at separate databases, the following configuration sections would route them to the database identifiers <tt>8</tt> and <tt>14</tt> respectively:

<pre>
clever:
groups: [clever_hosting]
id: 8

smart:
groups: [smart_hosting]
id: 14
</pre>

== Reload global db configuration ==

After updating the globaldb.yml you have to reload the server configuration by using /opt/open-xchange/sbin/reloadconfiguration command line tool.

[[Category: AppSuite]]
[[Category: Administrator]]
[[Category: Database]]

OX as a Service Provisioning using SOAP

2021-06-15T12:39:37Z

Choeger: /* User creation */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [https://www.open-xchange.com/portfolio/ox-dovecot-pro/ OX Dovecot Pro] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html
; about dialogue: com.openexchange.appsuite.servercontact, see below

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
},
{
'value' => 'My Example Org | <a href=\\"https://www.example.org\\" target=\\"_blank\\">www.example.org</a> | <a href=\\"https://example.org/help\\" target=\\"_blank\\">Contact us</a>',
'key' => 'com.openexchange.appsuite.servercontact'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">

package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.Entry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final long unifiedQuotaMax = 1000l;

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");
auser.setMaxQuota(unifiedQuotaMax);

// enable unified quota (might be enabled globally, already, though)
final Entry unifiedQuota = new Entry();
unifiedQuota.setKey("com.openexchange.unifiedquota.enabled");
unifiedQuota.setValue("true");

final SOAPStringMap configEntries = new SOAPStringMap();
configEntries.getEntries().add(unifiedQuota);

final SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
config.setValue(configEntries);

final SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(config);
auser.setUserAttributes(userattrs);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), unifiedQuotaMax, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if (oxaasport.existsLogin("auser", oxaasAdminCreds)) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2021-06-15T09:16:07Z

Choeger: /* User creation */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [https://www.open-xchange.com/portfolio/ox-dovecot-pro/ OX Dovecot Pro] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html
; about dialogue: com.openexchange.appsuite.servercontact, see below

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
},
{
'value' => 'My Example Org | <a href=\\"https://www.example.org\\" target=\\"_blank\\">www.example.org</a> | <a href=\\"https://example.org/help\\" target=\\"_blank\\">Contact us</a>',
'key' => 'com.openexchange.appsuite.servercontact'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">

package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.Entry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.user.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final long unifiedQuotaMax = 1000l;

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");
auser.setMaxQuota(unifiedQuotaMax);

// enable unified quota (might be enabled globally, already, though)
final SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
final SOAPStringMap configEntries = new SOAPStringMap();
final Entry unifiedQuota = new Entry();
unifiedQuota.setKey("com.openexchange.unifiedquota.enabled");
unifiedQuota.setValue("true");
configEntries.getEntries().add(unifiedQuota);
final SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(config);
auser.setUserAttributes(userattrs);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), unifiedQuotaMax, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if (oxaasport.existsLogin("auser", oxaasAdminCreds)) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

AppSuite:GuardCluster

2021-05-21T13:07:35Z

Choeger:

= OX Guard Clustering =

== IMPORTANT ==

'''If nothing else, make sure the oxguardpass file is the same for all Guard servers. This is the local password file that is used to encrypt some database items. If this varies between machines, there will be failures with password recoveries and cached key creation'''

== Pre-Installation ==

* Please make sure that the database is accessible from all of the Guard servers (usernames allow for the Guard IPs)
* Set up a filestore that can be accessed from all Guard servers. This may be a Networked File Store (NAS), or Amazon

== Setup ==

=== Configuration ===

==== OX Backends ====

On each OX backend, make sure the packages open-xchange-rest and open-xchange-guard-backend are installed. Edit the /opt/open-xchange/etc/server.properties file to make sure the REST API username and password are configured. Please see the setup instructions for details.

==== First machine ====

First, setup the guard.properties file to the needed settings.

* Make sure that the com.openexchange.guard.storage.file.uploadDirectory setting refers to the NAS
* Make sure the right username/password for the REST API are set
* Make sure all database settings are set for names that can be used from all guard servers (i.e. don't use localhost)
* If installing on the same server as an OX backend, it is possible to use localhost as the restAPIHostname, but if not, make sure goes through the same load balancer or routing as the users
** Guard uses JSESSIONID, like the user interface, for routing
** Guard uses the users cookie data to authorize against the backend to retrieve emails, etc.
** If routed to a different backend than the user, there will be excess sessions created

Run the <code>/opt/open-xchange/sbin/guard --init</code> '''on the first machine only'''

Once init is done, the oxguardpass file will be created. This file will need to be copied to all other Guard machines.

==== Other machines ====

Copy the oxguardpass file from the first installation into /opt/open-xchange/guard
Make sure that the guard.properties file for that machine is configured with the same required settings as the first. You may be able to just copy the guard.properties file from the first depending on your setup.

=== Startup ===

Once above is done, guard can be started.

AppSuite:GuardCluster

2021-05-21T12:46:40Z

Choeger:

= OX Guard Clustering =

== IMPORTANT ==

'''If nothing else, make sure the oxguardpass file is the same for all Guard servers. This is the local password file that is used to encrypt some database items. If this varies between machines, there will be failures with password recoveries and cached key creation'''

== Pre-Installation ==

* Please make sure that the database is accessible from all of the Guard servers (usernames allow for the Guard IPs)
* Set up a filestore that can be accessed from all Guard servers. This may be a Networked File Store (NAS), or Amazon

== Setup ==

=== Configuration ===

==== OX Backends ====

On each OX backend, make sure the packages open-xchange-rest and open-xchange-guard-backend are installed. Edit the /opt/open-xchange/etc/server.properties file to make sure the REST API username and password are configured. Please see the setup instructions for details.

==== First machine ====

First, setup the guard.properties file to the needed settings.

* Make sure that the com.openexchange.guard.storage.file.uploadDirectory setting refers to the NAS
* Make sure the right username/password for the REST API are set
* Make sure all database settings are set for names that can be used from all guard servers (i.e. don't use localhost)
* If installing on the same server as an OX backend, it is possible to use localhost as the restAPIHostname, but if not, make sure goes through the same load balancer or routing as the users
** Guard uses JSESSIONID, like the user interface, for routing
** Guard uses the users cookie data to authorize against the backend to retrieve emails, etc.
** If routed to a different backend than the user, there will be excess sessions created

Run the ./guard init on THE FIRST MACHINE ONLY

Once init is done, the oxguardpass file will be created. This file will need to be copied to all other Guard machines.

==== Other machines ====

Copy the oxguardpass file from the first installation into /opt/open-xchange/guard
Make sure that the guard.properties file for that machine is configured with the same required settings as the first. You may be able to just copy the guard.properties file from the first depending on your setup.

=== Startup ===

Once above is done, guard can be started.

AppSuite:OX Guard

2020-05-07T08:28:24Z

Choeger: /* Debian GNU/Linux 9.0 */

= OX Guard (Version 2.10) =

For previous versions of OX Guard, please click here
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]

If upgrading from 2.6 or 2.8, please see
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]

== Overview ==

OX Guard is a fully integrated security add-on to OX App Suite that provides end users with a flexible email and file encryption solution. OX Guard is a highly scalable, multi server, feature rich solution that is so simple-to-use that end users will actually use it. With a single click a user can take control of their security and send secure emails and share encrypted files. This can be done from any device to both OX App Suite and non-OX App Suite users.

OX Guard uses standard PGP encryption for the encryption of email and files. PGP has been around for a long time, yet has not really caught on with the masses. This is generally blamed on the confusion and complications of managing the keys, understanding trust, PGP format types, and lack of trusted central key repositories. Guard simplifies all of this, making PGP encryption as easy as a one click process, with no keys to keep track of, yet the options of advanced PGP management for those that know how.

This article will guide you through the installation of Guard and describes the basic configuration and software requirements. As it is intended as a quick walk-through it assumes an existing installation of the operating system including a single server App Suite setup as well as average system administration skills. This guide will also show you how to setup a basic installation with none of the typically used distributed environment settings. The objective of this guide is:

* To setup a single server installation
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster
* To use the database service on the existing Open-Xchange installation for Guard, no replication
* To provide a basic configuration setup, no mail server configuration

=== Key Features ===

* Simple security at the touch of a button
* Provides user based security - Separate from provider
* Supplementary security to Provider based security - Layered
* Powerful features yet simple to use and understand
* Security - Inside and outside of the OX environment
* Email and Drive integration
* Uses proven PGP security

=== Availability ===

If an OX App Suite customer would like to evaluate OX Guard integration, the first step is to contact OX Sales. OX Sales will then work on the request and send prices and license/API (for the hosted infrastructure) key details to the customer.

=== Requirements ===

Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.

Since OX Guard is a Microservice it can either be added to an existing Open-Xchange installation or it can be deployed on a dedicated environment. The version of Guard installed is dependent on the Appsuite version installed. Please refer to the version matrix below.

==== Prerequisites ====

* Open-Xchange REST API
* Grizzly HTTP connector (open-xchange-grizzly)
* A supported Java Virtual Machine (Java 8)
* An Open-Xchange App Suite installation (see version Matrix)
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [https://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages Updating OX-Packages] explains how that can be done.

==== Version Matrix ====
{|
! style="text-align:left;"| Core Version
! Guard Version
|-
|7.8.1
|2.4.0 or 2.4.2
|-
|7.8.2
|2.4.2
|-
|7.8.3
|2.6.0
|-
|7.8.4
|2.8.0
|-
|7.10.0
|2.10.0
|-
|7.10.1
|2.10.1
|-
|7.10.2
|2.10.2
|-
|7.10.3
|2.10.3
|}

=== Important Notes ===

==== Customisation ====

OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Check the [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization OX Guard Customisation] article for more details.

==== Mail Resolver ====

READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!

The Guard installation must be able to determine if an email recipient is a local OX user or if it should be a guest account. The default MailResolver uses the context domain name to do this. On many installations, domains may extend across multiple context and multiple database shards. In these cases, the default MailResolver won't work. In addition, if a custom authentication package is used, the Mail Resolver will likely not work.

Once Guard is installed, please be sure to test the mail resolver using:

<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source>
to see if the mail Resolver works.

If the test does not work, you will likely need a custom Mail Resolver. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver Mail Resolver] page

This resolver software ''depends heavily on your local deployment''.

== Download and Installation ==

=== General ===

The installation of the <code>open-xchange-guard-backend-plugin</code> package which is required for Guard and the main <code>open-xchange-guard</code> package in version 2.4.0 or higher will eventually execute database update tasks if installed and activated. Please take this into account.

There are several components to the Guard service. They can be all installed on the same server as the OX middleware or on a separate server.

The components required for the OX middleware are: <code>open-xchange-rest</code>, <code>open-xchange-guard-backend-plugin</code> and <code>open-xchange-guard-ui</code>.

The components required for the OX frontend are: <code>open-xchange-guard-ui-static</code> and optionally <code>open-xchange-guard-help-en-us</code> (or preferred language for help files).

The components required for the Guard server <code>open-xchange-guard</code> and either <code>open-xchange-guard-file-storage</code> or <code>open-xchange-guard-s3-storage</code> depending on what storage you want to use. The examples below make use of the <code>open-xchange-guard-file-storage</code>. Adjust the commands accordingly to fit your needs. In addition <code>open-xchange</code> and <code>open-xchange-core</code> are required to run OX Guard.

=== Debian Linux 8.0 (Jessie) ===

Support of Debian Jessie is deprecated. Read More: https://forum.open-xchange.com/showthread.php?11205

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /

and then run for a single node installation:

$ apt-get update
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin

or the following for a distributed installation:

$ apt-get update
$ apt-get install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== RedHat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage
The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard]
name=Open-Xchange-guard-stable-guard
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and then run for a single node installation:

$ yum update
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static open-xchange-guard-backend-plugin
or the following for a distributed installation:

$ yum update
$ yum install open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using zypper if not already present:

$ zypper ar https://software.open-xchange.com/products/guard/stable/guard/SLE_12 guard-stable-guard
$ zypper ar https://software.open-xchange.com/products/appsuite/stable/backend/SLE_12 ox-backend

and then run for a single node installation:

$ zypper ref
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static

or the following for a distributed installation:

$ zypper ref
$ zypper in open-xchange-guard open-xchange-guard-file-storage

The packages <code>open-xchange-guard-ui</code> <code>open-xchange-rest</code> and <code>open-xchange-guard-backend-plugin</code> missing in the distributed installation have to be installed on the node running the middleware. The package <code>open-xchange-guard-ui-static</code> must be installed in the frontend (apache node).

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Guard at your already available environment.

Please note: By default, OX Guard generates the link to the secure content for external recipients on the basis of the local fully qualified domain name (FQDN). If the local FQDN is not reachable from the Internet, it has to be specified manually. This can be done by setting a UCR variable, e.g. via the UMC module "Univention Configuration Registry". The variable has to contain the external FQDN of the OX Guard system:

<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source>

== Update OX Guard ==

This section contains information about updating a 2.10.0 version (e.g. for patch fixes). Upgrading from prior versions is discussed in different articles.

=== Debian Linux 8.0 (Jessie) ===

Support of Debian Jessie is deprecated. Read More: https://forum.open-xchange.com/showthread.php?11205

=== Debian Linux 9.0 (Stretch) ===

If not already done, add the following repositories to your Open-Xchange apt configuration:

deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>>

Then run:

$ apt-get update
$ apt-get dist-upgrade</source>

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s</source>

=== Redhat Enterprise Linux 6 or CentOS 6 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== Redhat Enterprise Linux 7 or CentOS 7 ===

If not already done, add the following repositories to your Open-Xchange yum configuration:

[open-xchange-guard-stable-guard-updates]
name=Open-Xchange-guard-stable-guard-updates
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-backend]
name=Open-Xchange-backend
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=https://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m</source>

and then run:

$ yum update
$ yum upgrade</source>

=== SUSE Linux Enterprise Server 12 ===

Add the package repository using <code>zypper</code> if not already present:

$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/SLE_12 guard-stable-guard-updates
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12 ox-backend</source>

and then run:

$ zypper dup -r guard-stable-guard-backend-updates
$ zypper dup -r guard-stable-guard-ui-updates</source>

You might need to run:

$ zypper ref</source>

to update the repository metadata before running <code>zypper</code> up.

=== Univention Corporate Server ===

If you have purchased the OX App Suite for UCS, the OX Guard is part of the offering. OX Guard is available in the Univention App Center. Please check the UMC module App Center for the update of the OX Guard.

== Configuration ==

The following gives an overview of the most important settings to enable Guard for users on the Open-Xchange installation. Some of those settings have to be modified in order to establish the database and REST API access from the Guard service. All settings relating to the Guard backend component are located in the configuration file <code>guard-core.properties</code> located in <code>/opt/open-xchange/etc</code>. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the database username and password). Please refer to the inline documentation of the configuration file for more advanced options. Additional information can be found in the [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Configuration_2_10 Guard Configuration] article.

=== Basic Configuration ===

<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source>
Guard database for storing Guard user information, main lookup tables:

<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source>
Guard database that stores keys for guest users. May be the same as above. New guest shards will be created on this database as needed. If not supplied, will use the <code>oxguardDatabaseHostname</code>:

<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source>
Username and Password for the databases above:

<source lang="bash">com.openexchange.guard.databaseUsername=openexchange
com.openexchange.guard.databasePassword=db_password</source>
Open-Xchange REST API host:

<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source>
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below):

<source lang="bash">com.openexchange.guard.restApiUsername=apiusername
com.openexchange.guard.restApiPassword=apipassword</source>
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:

<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source>
=== Middleware Configuration on OX Guard node ===

If you are installing OX Guard on a node that until yet did not host an Open-Xchange middleware you have to additionally configure some parts of the following properties files:

* <code>configdb.properties</code>: information about the existing configuration database.
* <code>server.properties</code>: information about the connections have to be set.
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.

=== Sevices Configuration ===

==== Apache ====

Configure the <code>mod_proxy_http</code> module by adding the Guard API.

===== Redhat Enterprise Linux 6 or CentOS 6 =====

<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source>

===== Debian GNU/Linux 9.0 =====

<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source>

<Proxy balancer://oxguard>
Order deny,allow
Allow from all

BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard
ProxyPass /pks balancer://oxguard/pgp
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu

'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.

'''Also Note''': If you already have a Proxy balancer for the OX backend with the same URL (say http://localhost:8080) then you don't need the second BalancerMember entry, and you can just have the ProxyPass address that balancer instead.

After the configuration is done, restart the Apache webserver

<source lang="bash">$ apachectl restart</source>

=== Open-Xchange Middleware Configuration ===

Edit the <code>guard-api.properties</code> configuration file for the OX backend where the guard-backend-plugin was installed. Please remove comments in front of the following settings to the configuration file <code>guard-api.properties</code> on the Open-Xchange backend servers:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.
com.openexchange.capability.guard=true

# Default theme template id for all users that have no custom template id configured.
com.openexchange.guard.templateID=0</source>
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.login=apiusername

# Specify the password used for HTTP basic auth by internal REST servlet
com.openexchange.rest.services.basic-auth.password=apipassword</source>
Finally, the OX backend needs to know where the Guard server is located. This is used to notify the Guard server of changes in users, and to send emails marked for signature. The URL for the Guard server should include the URL suffix <code>/guardadmin</code>. In the event of a cluster setup, any Guard server can be referenced here, as it is not session specific, though ideally would have a HTTP load balancer/failover URL:

<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source>
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin
# Default is empty
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source>
Restart the OX backend

<source lang="bash">$ /etc/init.d/open-xchange restart</source>
==== SELinux ====

Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8009, which is where the Guard backend service listens to. In order to allow localhost connections to 8009 execute the following:

<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source>
=== Generating the <code>oxguardpass</code> ===

Once the Guard configuration (database and backend configuration) and the service configuration has been applied, the Guard administration script needs to be executed in order to create the master password file in <code>/opt/open-xchange/etc/oxguardpass</code>. The initiation only needs to be done '''once''' for a multi server setup, for details please see the sections '''Optional''' and/or '''Clustering'''.

'''Please Note''': If you run a cluster of OX / Guard nodes, only execute this command on '''ONE''' node. Not on all nodes! See [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering] for details.

<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source>
'''Please Note''': It is important to understand that the master password file located at <code>/opt/open-xchange/etc/oxguardpass</code> is required to reset user passwords; without them the administrator will not be able to reset user passwords anymore in the future. The file contains the passwords used to encrypt the master database key, as well as passwords used to encrypt protected data in the users table. It must be the same on all Guard servers.

=== Test Setup ===

Not required, but it is a good idea to test the Guard setup before enabling for any users. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.

To test, use an email address that exists on the OX backend (john@example.com for this example)

<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source>
Guard should return information from the OX backend regarding the user associated with "john@example.com". Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.

=== Enabling Guard for Users ===

Guard provides two capabilities for users in the environment as well as a basic "core" level:

* Guard: <code>com.openexchange.capability.guard</code>
* Guard Mail: <code>com.openexchange.capability.guard-mail</code>
* Guard Drive: <code>com.openexchange.capability.guard-drive</code>

The "core" Guard enabled a basic read functionality for Guard encrypted emails. We recommend enabling this for all users, as this allows all recipients to read Guard emails sent to them. Great opportunity for upsell. Recipients with only Guard enabled can then do a secure reply to the sender, but they can't start a new email or add recipients.

'''Guard Mail''' and '''Guard Drive''' are additional options for users. "Guard Mail" allows users the full functionality of Guard emails. "Guard Drive" allows for encryption and decryption of drive files.

Each of those two Guard components is enabled for all users that have the according capability configured. Please note that users need to have the Drive permission set to use Guard Drive. So the users that have Guard Drive enabled must be a subset of those users with OX Drive permission. Since v7.6.0 we enforce this via the default configuration. Those capabilities can be activated for specific user by using the Open-Xchange provisioning scripts:

==== Guard Mail: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true</source>
==== Guard Drive: ====

<source lang="bash">$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true</source>
'''Please Note''': Guard Drive requires Guard Mail to be configured for the user as well. In addition, these capabilities may be configured globally by editing the <code>guard-api.properties</code> file on the OX backend.

=== External Guest recipients: ===
Starting in Guard 2.10.0, when an encrypted email is sent to a user that does not have Guard, a guest account is created for them in appsuite. The recipient uses the Guest account to read the encrypted email. These guest users MUST have guard capabilities. To do this, guard capability must be added to guest accounts.
<code>/opt/open-xchange/etc/share.properties</code>
<source lang="bash">com.openexchange.share.guestCapabilityMode=static
com.openexchange.share.staticGuestCapabilities=guard</source>
In a distributed system, the Guest accounts should not be considered transient. Guard servers must be able to verify the guest account exists in the session storage services.
<source lang="bash">com.openexchange.share.transientSessions=false</source>

=== Guest Storage ===
When an encrypted email is sent to an external Guest, a copy of the fully encrypted email is stored on the server. This is used to create an inbox of encrypted emails for the guest. By entering in a password, the emails can be decrypted and displayed.

How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.

The file retention policy is configured in the guard-core.properties file.

=== Recipient key detection ===

==== Local ====

Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.

To detect if the recipient is an account on the same OX Guard system there is a mechanism needed to map a recipient mail address to the correct local OX context. The default implementation delivered in the product achieves that by looking up the mail domain (@example.com) within the list of context mappings. That is at least not possible in case of ISPs where different users/contexts use the same mail domain. In case your OX system does not use mail domains in context mappings it is required to deploy an OX OSGi bundle implementing the <code>com.openexchange.mailmapping.MailResolver</code> class or by interfacing Guard with your mail resolver system. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardMailResolver OX Guard Mail Resolver] for details.

==== External ====

Starting with Guard 2.0, Guard will use public PGP Key servers if configured to find PGP Public keys. In addition, Guard will also look up SRV records for PGP Key servers for a recipients domain. This follows the standards [http://tools.ietf.org/html/draft-shaw-openpgp-hkp-00#page-9 OpenPGP Draft].

External PGP servers to use can be configured in the guard.properties file on the Guard servers.

<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source>
If you would like this Guard installation discoverable by other Guard servers, then create an SRV record for each domain ("example.com" in this illustration):

<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source>

'''Please Note''' PGP Public key servers by default append use the URL server/pks when the record is obtained from an SRV record. The proxy above routes anything with the Apache domain/pks to the OX Guard PGP server.

Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02
This is enabled if you include the
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source>
in the proxy_http.conf as above.

=== Clustering ===

You can run multiple OX Guard servers in your environment to ensure high availability or enhance scalability. OX Guard integrates seamlessly into the existing Open-Xchange infrastructure by using the existing interface standards and is therefor transparent to the environment. A couple of things have to be prepared in order to loosely couple OX Guard servers with Open-Xchange servers in a cluster.

==== MySQL ====

The MySQL servers need to be configured in order to allow access to the configdb of Open-Xchange. To do so you need to set the following configuration in the MySQL <code>my.cnf</code>:

<source lang="bash">bind = 0.0.0.0</source>
This allows the Guard backend to bind to the MySQL host which is configured in the <code>guard-core.properties</code> file with <code>com.openexchange.guard.configdbHostname</code>. After the bind for the MySQL instance is configured and the OX Guard backend would be able to connect to the configured host, you have to grant access for the OX Guard service on the MySQL instance to manage the databases. Do so by connecting to the MySQL server via the MySQL client. Authenticate if necessary and execute the following, please note that you have to modify the hostname / IP address of the client who should be able to connect to this database, it should include all possible OX Guard servers:

<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source>

==== Apache ====

OX Guard uses the Open-Xchange REST API to store and fetch data from the Open-Xchange databases. The REST API is a servlet running in the Grizzly container. By default it is not exposed as a servlet through Apache and is only accessibly via port 8009. In order to use Apache's load balancing via <code>mod_proxy</code> we need to add a servlet called "preliminary" to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:

<Location /preliminary>
Order Deny,Allow
Deny from all
# Only allow access from Guard servers within the network. Do not expose this
# location outside of your network. In case you use a load balancing service in front
# of your Apache infrastructure you should make sure that access to /preliminary will
# be blocked from the Internet / outside clients. Examples:
# Allow from 192.168.0.1
# Allow from 192.168.1.1 192.168.1.2
# Allow from 192.168.0.
</Location>

ProxyPass /preliminary balancer://oxcluster/preliminary

Make sure that the balancer is properly configured in the <code>mod_proxy</code> configuration. Examples on how to do so can be found in our clustering configuration for Open-Xchange AppSuite. Like explained in the example above, please make sure that this location is only available in your internal network, there is no need to expose <code>/preliminary</code> to the public, it is only used by Guard servers to connect to the OX backend. If you have a load balancer in front of the Apache cluster you should consider blocking access to <code>/preliminary</code> from WAN to restrict access to the servlet to internal network services only.

Now add the OX Guard <code>BalancerMembers</code> to the oxguard balancer configuration (also in <code>proxy_http.conf</code>) to address all your OX Guard nodes in the cluster in this balancer configuration. The configuration has to be applied to all Apache nodes within the cluster.

If the Apache server is a dedicated server <code>/</code> instance you also have to install the OX Guard UI-Static package on all Apache nodes in the cluster in order to provide static files like images or CSS to the OX Guard client. Example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source>

==== Open-Xchange ====

Disable the Open-Xchange IPCheck for session verification. This is required because OX Guard will use the users session cookie to connect to the Open-Xchange REST API, but as a different IP address than the OX Guard server has been used during authentication the request would fail if you don't disable the IPCheck:

<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source>
and set:

<source lang="bash">com.openexchange.IPCheck=false</source>
The OX Guard UI package has to be installed on all Open-Xchange backend nodes as well, example for Debian (the OX Guard repository has to be configured in the package management prior):

<source lang="bash">$ apt-get install open-xchange-guard-ui</source>
Restart the Open-Xchange service afterwards.

==== OX Guard ====

For details in clustering Guard servers, please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCluster OX Guard Clustering]. It is '''critical''' that all Guard servers have the same <code>oxguardpass</code> file. Please see the clustering link for details. Do not run <code>/opt/open-xchange/sbin/guard --init</code> on more than one server.

After all the services like MySQL, Apache and Open-Xchange have been configured you need to update the OX Guard backend configuration to point to the correct API endpoints. Set the REST API endpoint to an Apache server by setting the following value in <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source>
Per default Guard will try to connect to port 8009 to this host, but as we configured the REST API to be proxies thorugh the servlet <code>/preliminary</code> on every Apache we now also need to change the target port for the REST API. You can do so by adding the following line into <code>/opt/open-xchange/etc/guard-core.properties</code>:

<source lang="bash">com.openexchange.guard.oxBackendPort=80</source>
Please also change all settings in regards to MySQL like <code>com.openexchange.guard.configdbHostname</code>, <code>com.openexchange.guard.oxguardDatabaseHostname</code>, <code>com.openexchange.guard.databaseUsername</code> or <code>om.openexchange.guard.databasePassword</code>.

Afterwards restart the OX Guard service and check the log file if the OX Guard backend is able to connect to the configured REST API.

=== Multi Node ===

If you have multiple OX and Guard installations, please see the following documentation [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard_Modular OX Guard Modular Setup].

== Support API ==

The OX Guard Support API enables administrative access to various functions for maintaining OX Guard from a client in a role as a support employee. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard-core.properties file using the following settings:

# Specify the username and password for accessing the Support API of Guard
com.openexchange.guard.supportApiUsername=
com.openexchange.guard.supportApiPassword=

In contrast to the rest of the OX Guard requests, the OX Guard support API requests are accessible using: /guardsupport. This distinction allows more flexible configuration since the support API should not always be accessible from everywhere.

'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.

=== Reset password ===

<code>POST /guardsupport/?action=reset_password</code>

Performs a password reset and sends a new random generated password to a specified email address by the user or a default address if the user did not specify an email address. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to reset the password for
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address

Response:
PRIMARY if the reset was sent to the primary email address. SECONDARY if the reset email was sent to the secondary email address that the user specified

=== Expose key ===

<code>POST /guardsupport/?action=expose_key</code>

Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to "not exposed" is scheduled once a day and resets all exposed keys which have been exposed before X hours, where X can be configured using com.openexchange.guard.exposedKeyDurationInHours in the guard.properties files. (''Since Guard 2.0'')

Parameters:

* <code>email</code> – The email address of the user to expose the deleted keys for
* <code>cid</code> – The context id

Response: A URL pointing to the downloadable exposed keys.

=== Delete user ===

<code>POST /guardsupport/?action=delete_user</code>

Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call. (''Since Guard 2.0'')

Parameters:

* <code>user_id</code> – The user's id
* <code>cid</code> - The context id

=== Upgrade User (Release 2.10 and later) ===

<code>POST /guardsupport/?action=upgrade_guest</code>

Upgrades a Guest account. This action copies all of the keys from the Guest account to a full OX account, assuming that user has Guard capabilities.

Parameters:

* <code>email</code> - The email address of the Guest user
* <code>user_id</code> – The user's new id
* <code>cid</code> - The user's new context id

== Customisation ==

Guard's templates are customisable at the user and context level. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardCustomization Customisation] for details.

== Entropy ==

Guard requires entropy (randomness) to generate the private/public keys that are used. Depending on the server and it's environment, this may become a problem. Please see [https://oxpedia.org/wiki/index.php?title=AppSuite:GuardEntropy Entropy] for a possible solution.

OX as a Service Provisioning using SOAP

2020-04-21T11:07:12Z

Choeger: /* Create a context */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [https://www.open-xchange.com/portfolio/ox-dovecot-pro/ OX Dovecot Pro] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html
; about dialogue: com.openexchange.appsuite.servercontact, see below

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
},
{
'value' => 'My Example Org | <a href=\\"https://www.example.org\\" target=\\"_blank\\">www.example.org</a> | <a href=\\"https://example.org/help\\" target=\\"_blank\\">Contact us</a>',
'key' => 'com.openexchange.appsuite.servercontact'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2020-04-21T10:56:58Z

Choeger: /* userAttributes */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [https://www.open-xchange.com/portfolio/ox-dovecot-pro/ OX Dovecot Pro] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
},
{
'value' => 'My Example Org | <a href=\\"https://www.example.org\\" target=\\"_blank\\">www.example.org</a> | <a href=\\"https://example.org/help\\" target=\\"_blank\\">Contact us</a>',
'key' => 'com.openexchange.appsuite.servercontact'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

AppSuite:Documents Installation Guide

2020-01-21T07:58:39Z

Choeger: either sudo or not sudo

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Note:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
sudo a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-01-21T07:57:10Z

Choeger: /* Documents Collaboration Service (DCS) */

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Note:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database.

'''Note:
Before you can use this tool, you have to edit /opt/open-xchange/etc/documents-collaboration-client.properties in order to adapt it
to use the db username and password you configured above.
'''
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-01-21T07:53:03Z

Choeger: either sudo or not sudo

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Note:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database
<pre>
# sudo /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Documents Installation Guide

2020-01-21T07:49:49Z

Choeger: either sudo or not sudo

{{Version|7.10.3}}

For earlier versions see ''[[AppSuite:Documents_Installation_Guide_7.10.2_and_earlier|Guide for 7.10.2]]''

= Download & Installation OX Documents =

=== General Information ===

OX Documents are browser based, cloud ready, text, spreadsheet and presentation products that can work with Microsoft Office and OpenOffice documents in a lossless way. And you can also collaborate with other people to edit shared documents on various devices.

== Requirements ==

See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details. Additionally the support of websockets proxy by the webserver or loadbalancer is required, this is e.g. available in Apache 2.4.10 and higher.

OX Documents needs to be installed in an OX App Suite configuration with a [[AppSuite:Grizzly|backend based on Grizzly]] (including hazelcast as installed and activated by default).

For compatibility with the legacy MS binary format files (.DOC, .XLS, .PPT) and for printing functionality in OX Text the document converter components (incl. readerengine) are required. These are not available in the Community Version of OX AppSuite.



== Installation ==

The OX Documents deployment consists of the packages <tt>open-xchange-documents-backend</tt> and <tt>open-xchange-documents-ui</tt>. The <tt>open-xchange-documents-backend</tt> package also requires and installs these packages:

* <tt>open-xchange-file-distribution</tt>
* <tt>open-xchange-sessionstorage-hazelcast</tt>

The following Packages are no longer needed since 7.10.3
* <tt>open-xchange-realtime-core</tt>
* <tt>open-xchange-realtime-json</tt>
Furthermore all <tt>open-xchange-realtime-*</tt> packages will be replaced with empty transitive packages to remove relicts of the realtime framework.

The package <tt>open-xchange-documents-collaboration</tt> has been introduced with 7.10.3. It provides the Documents Collaboration Service (see below).

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}
$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static documents-collaboration

'''Note:
The Apache version 2.2 provided with RHEL6 does not support websockets.
Please use Apache version 2.4.x available with RHSCL or any other capable loadbalancer.'''

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ yum install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 9.0 (valid from v7.10) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Debian GNU/Linux 10.0 (valid from v7.10.3) ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianBuster|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration/updates}}

$ apt-get update
$ apt-get install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|office|office-web|documentconverter-api|documents-collaboration}}

if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|office/updates|office-web/updates|documentconverter-api/updates|documents-collaboration}}

$ zypper ref
$ zypper install open-xchange-documents-backend open-xchange-documents-ui open-xchange-documents-ui-static open-xchange-documents-collaboration

=== Univention Corporate Server ===

OX Text for OX App Suite for UCS is available in the Univention App Center. Please check the UMC module App Center for the installation of the OX Documents at your already available environment.

== Documents Collaboration Service ==

Starting with release 7.10.3 the Documents Collaboration Service (DCS) has been introduced.

The DCS needs to be installed, configured and run. It supports collaboration across Middleware nodes but is also mandatory for small (even single node) environments.
The server can be run as one additional service (JVM) or - for larger deployments - several instances can be clustered.
The implementation is based on Spring Boot and uses the Java-based messaging server Apache ActiveMQ.

'''Note:
For upgrades from earlier versions than 7.10.2 the hazelcast cluster requires a complete shutdown, since the internal OX Documents data has changed. A rolling upgrade is not possible.'''

=== Documents Collaboration Service (DCS) ===

Prepare documents-collaboration repository as described above.

The DCS will be installed via the package:
<pre>
open-xchange-documents-collaboration
</pre>

The target directory is /usr/share/open-xchange-documents-collaboration

The DCS configuration file is located at /etc/documents-collaboration/dcs.properties. All available configuration items are described on this [https://documentation.open-xchange.com/components/documents/documents-collaboration/config/7.10.3/#mode=features&feature=DocumentsCollaboration%20Server page]

The following entries need to be reviewed and values need to be adjusted during the setup. 
Configure bind host IP and JMS Port to listen to
<pre>
dcs.host = 192.168.10.25 # Interface of the DCS node
dcs.port = 61616
</pre>

A DCS writes its own connection data, retrieved from its configuration file during startup of the service, to a database to be discovered by Middleware nodes.

'''Caveat:
In a distributed setup DCSs may be installed on separate nodes. If such a DCS node has different internal and external IP addresses one needs to make sure that a middleware node has the correct DCS address to connect to.
The config item <tt>advertiseURL</tt> can be set to the name of the DCS node.
<pre>dcs.advertiseURL=dcs.example.com:61616</pre>
Additionally the address of the internal interface should resolved to the hostname; e.g. /etc/hosts reads like
<pre>192.168.10.25 dcs.example.com</pre>
Especially on debian systems it might be necessary to modify /etc/hosts accordingly (and remove the 127.0.1.1 line).
'''

The database schema for the DCS as well as appropriate database access data for the DCS user need to be created and set at the configured database prior to starting up the DCS for the first time. The database connection properties to be used by the DCS need to be set at the configuration file as well:

<pre>
db.host=192.168.10.172
db.port=3306
db.schema=dcsdb
db.username=db_user
db.password=db_password
</pre>

After setting these database related properties within the /etc/documents-collaboration/dcs.properties file, the admin needs to call the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script as super user of the system.

Database related settings made in the /etc/documents-collaboration/dcs.properties file are read by this script first and taken as defaults. Nevertheless, each default value can be overwritten by the admin via the command line. Passwords need to be set by the admin via the command line in every case for security reasons.

If all database properties have been set correctly within the /etc/documents-collaboration/dcs.properties file, a valid call to the /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh script is e.g. the following one:

<pre>
sudo /usr/share/open-xchange-documents-collaboration/bin/initdcsdb.sh -a --dcsdb-pass=db_password --mysql-root-passwd=mysql_password
</pre>

The default logging path is set in /etc/documents-collaboration/logback-spring.xml and points to /var/log/open-xchange/documents-collaboration/documents-collaboration.log

The Documents Collaboration Service will be started by executing the following comand:
<pre>
sudo systemctl start open-xchange-documents-collaboration.service
</pre>

A command line tool allows to check the values in the database
<pre>
# /usr/share/open-xchange-documents-collaboration/bin/documents-collaboration-admin.sh -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>
JMX access to the DCS can be enabled and configured in dcs.properties.
By default it is disabled. To enable JMX change the appropriate line to
<pre>
jmx.enabled=true
</pre>

===Middleware node===

No additional package repositories and no additional packages are required to be installed for the Middleware in order to use DCS.

Discovery of running DCSs via the database is configured in file /opt/open-xchange/etc/documents-collaboration-client.properties.
Add the appropriate values to access the ''dcsdb'' Database as previously set during the DCS configuration (see above):
<pre>
com.openexchange.dcs.client.database.connectionURL=jdbc:mysql://192.168.10.172:3306/dcsdb
com.openexchange.dcs.client.database.userName=db_user
com.openexchange.dcs.client.database.password=db_password
</pre>

A command line tool allows to check the values in the database
<pre>
$ /opt/open-xchange/sbin/documents-collaboration-admin -l
+---------------------+---------------+---------------+---------+
| ID | Host | Interface | JMSPort |
+---------------------+---------------+---------------+---------+
| 192.168.10.25:61616 | 192.168.10.25 | 192.168.10.25 | 61616 |
+---------------------+---------------+---------------+---------+
</pre>

===Apache configuration===

For working websocket support Apache version 2.4.10 or newer is required.

The Apache module proxy_wstunnel has to be enabled:
<pre>
a2enmod proxy_wstunnel
</pre>

and the the following entries need to be added to the Apache configuration:
<pre>
<Proxy balancer://oxcluster_ws>
Order Deny,Allow
Allow from all
BalancerMember ws://localhost:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /appsuite/rt2 balancer://oxcluster_ws/rt2
</pre>

A running Apache server on the system needs to be restarted or triggered to reload its configuration after the above changes have been made.

== Monitoring ==

OX Documents offers runtime information via JMX about the document editors as well as the OX Documentconverter. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.

== Printing and legacy MS binary formats Editing ==

For .DOC/.XLS/.PPT and/or printing support from OX Documents the Document Converter and readerengine components have to be installed separately (license key required)

* See [[AppSuite:DocumentConverterInstall|Document converter / readerengine installation instructions]]

== Configuration ==

=== Permissions ===

To enable the OX Documents Applications for OX Drive the associated permission has to be set.

The default setting for all users is changed in the file '''documents.properties''' in the directory ''/opt/open-xchange/etc''.

After installation the functionality is disabled:
<pre>
# Enables or disables the "text" module capability globally.
# com.openexchange.capability.text=true

# Enables or disables the "spreadsheet" module capability globally.
# com.openexchange.capability.spreadsheet=true

# Enables or disables the "presentation" module capability globally.
# com.openexchange.capability.presentation=true

</pre>

The following line enables the functionality:
<pre>
# Enables or disables the "text" module capability globally.
com.openexchange.capability.text=true
</pre>

Starting with 7.6.2, you can disable the text portal app. In '''permissions.properties''':
<pre>
permissions=textportaldisabled
</pre>

=== Collaboration on shared documents ===

If OX Documents functionality is used for guest users in a cluster of application servers, this setting needs to be adjusted to false in order to also have guest sessions available in the distributed storage.

in ''/opt/open-xchange/etc/sharing.properties''

<pre>
# Specifies whether guest sessions are treated as transient or not. Transient
# sessions are only held in the short-term session containers, and are not put
# into the distributed session storage. Defaults to "true".
com.openexchange.share.transientSessions=false
</pre>

com.openechange.share.transientSessions has to be set to false.

=== Spell Checking===

OX Text and OX Presentation use ''hunspell'' for spell checking functionality.
By default Spellchecking is enabled in ''/opt/open-xchange/etc/settings/office.properties''
with the following entry
<pre>
# Determines whether online spelling is enabled for office documents.
# Possible values: true|false
# If this property is missing true is taken.
io.ox/office//module/spellingEnabled=true
</pre>

After installation of the ''hunspell'' package for your platform the shared library and the US English dictionaries are available. Please check the file location the pkg files were installed into. (For instance on CentOS, use rpm -q –filesbypkg hunspell and verify the path of the lib files to be configured below)
Also verify that the Hunspell dictonary is present and not renamed to "myspell" etc.. if the dictionary is renamed, you will have to use that in the config below.

Additional dictionaries are published for your platform as packages hunspell-de-de, hunspell-fr, ...

Spell checking has to be configured in the file ''/opt/open-xchange/etc/hunspell.properties''.
The values for the shared library file and dictionary path have to be set according to the platform.

This example shows the values for Debian:

<pre>
# The name and location of the hunspell library
# Default value: "/usr/lib/x86_64-linux-gnu/libhunspell-1.3.so.0"
com.openexchange.spellchecker.hunspell.library=/usr/lib/x86_64-linux-gnu/libhunspell-1.4.so.0
# The location of the dictionaries
# Default value: "/usr/share/hunspell"
com.openexchange.spellchecker.hunspell.dictionaries=/usr/share/hunspell
</pre>

If spellchecking is enabled and the library path or dictionary path is wrong a warning is logged.

If a language is not supported by a hunspell dictionary (or produces error messages in the console log) myspell dictionaries are a working alternative.

=== Templates ===

OX Documents support different levels to provide document templates for users.

A number of ready-to-use templates for letters, memos, resumes, home budget, presentations, etc is included with the system. These templates are made available in a directory at each system node by installation of the package open-xchange-documents-templates. The path to this directory is defined in the office.properties file

<pre>
# Defines the absolute path where document templates are located inside the local (!) file system.
# The templates are displayed in the documents applications.
# If this property is missing a default '/opt/open-xchange/templates/documents' is taken.
io.ox/office//module/templatePath = /opt/open-xchange/templates/documents
</pre>

The content in the directory specified by the path must comply to the following rules:

<pre>
/opt/open-xchange/templates/documents
|
----> text [application type]
| |
| ----> en-US [language-region]
| |
| ----> en [language fallback, en is also fallback for all other non-convered languages]
| |
| ----> de-DE
| |
| ----> de
| |
| ----> common [language independent, used in addition to the language specific ones]
|
----> spreadsheet
|
----> presentation
</pre>

A context administrator can additionally provide global templates for all users in the same context.
If logged in with this role folders can be added to or removed from the list of global template folders. For regular users the list is displayed without the permission to modify it.

[[File:template-folder.png|border|600px|caption]]

Users can create and manage their own templates. These user templates are stored and retrieved from the user’s root folder (“My files”). In addition to the root folder the user can define more template folders, sub-folders or even external folders in the “Documents” section of the “Settings” menu. This helps to organize templates and allows cleanup of the root folder by removal of templates.

For installations of OX Spreadsheet based on Appsuite 7.8.0 and 7.8.1 please see [http://oxpedia.org/wiki/index.php?title=AppSuite:Spreadsheet_Installation_Guide_7_8_1 here] for different installation modes.

=== OX Documents in Browser Tabs ===

OX Documents based on Appsuite 7.10.2 opens new documents in new tabs in the browser by default.

To disable this feature an stay in the single tab mode you have to set the attribute 'openInSingleTab' in as-config.yml
<pre>
# Override certain settings
default:
host: all
openInSingleTab: true
</pre>

AppSuite:Mobile API Facade

2019-12-11T10:03:46Z

Choeger:

= Mobile API Facade =

== General Information ==

The Mobile API Facade is a server component that brings the new native mobile mail apps together with the OX App Suite. We’ve built the façade based on the technology used and proven in the OX App Suite middleware. The facade is developed in Java, utilizing the OSGI Framework.

The Facade provides offline friendly HTTP interface by doing the work, the connections through the HTTP API, to the OX App Suite and providing only the data the offline capable clients need. In some cases multiple requests to the OX App Suite are combined into one for its clients.The facade also offers a method to tell the clients that information on the server haven’t changed since the last time the client asked for it. This reduces the amount of data to transmit to the clients under certain circumstances, especially important in mobile networks were bandwidth (and overall traffic) is limited. Thanks to facade some functionality can be shared among all clients and need only get implemented once. One example for this is the teaser text extraction, and HTML mail handling in general.The facade also provides a pluggable authentication system. In the default case, login request are just forwarded to the middleware. In more advanced use-cases, the login request is forwarded to IDM of the customer and an OX session is created from the access token from the IDM. For clients this is pretty straightforward.

== License information ==

=== Used 3rd party licenses ===

In addition to the 3rd party software [https://www.open-xchange.com/legal/licenses-ox-app-suite/ used by AppSuite], the Mobile API Facade uses to following libraries:

* [https://www.open-xchange.com/fileadmin/user_upload/images/portfolio/license/MIT_License_Generic.pdf Project Lombok (The MIT License]
* [https://www.open-xchange.com/fileadmin/user_upload/images/portfolio/license/MIT_License_Generic.pdf Semver4J (The MIT License)]

== Requirements ==

The Mobile API Facade has to be installed alongside an OX App Suite installation. It requires at least OX App Suite v7.8.4.

== Version Matrix ==
{|border="2" rules="all" align="left">
|-
|colspan=1|'''OX App Suite Core Version'''
|colspan=1|'''Mobile API Facade Version'''
|colspan=1|'''Version-Stream'''
|-
|v7.8.4
|v1.0.x
|stable-1.0
|-
|v7.10.0
|v1.2.x
|stable-1.2
|-
|v7.10.1
|v1.4.x
|stable-1.4
|-
|v7.10.2
|v1.6.x
|stable-1.6
|-
|v7.10.3
|v1.8.x
|stable-1.8
|-
|}

== Mobile API Facade API ==

Further information about the Mobile API Facade API can be found at:
https://documentation.open-xchange.com/components/facade/1.0.0/

= OX Mail Server-side Installation and Configuration on OX App Suite v7.10.3 =

This chapter describes how the backend components of OX Mail are installed and configured on the server.

== Available packages ==

Mobile API Facade is available with the following backend packages:

* ''open-xchange-mobile-api-facade''

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=rhelname|pc2v=RHEL6|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=rhelname|pc2v=RHEL7|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Debian GNU/Linux 9.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=debianname|pc2v=DebianStretch|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== Debian GNU/Linux 10.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=debianname|pc2v=DebianBuster|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/stable-1.8|pc2n=susename|pc2v=SLE_12|mobile-api-facade}}

$ zypper ref
$ zypper install open-xchange-mobile-api-facade

= OX Mail Server-side Installation and Configuration on OX App Suite 7.8.x and 7.10.x =

If you want to update an older version of OX Mobile API Facade to the latest maintenance release, add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>. Replace VERSION with the link for the stream of versions as listed above in the version matrix (e.g. stable-1.2) or a specific version you are using (e.g. 1.2.3).

This chapter describes how the backend components of OX Mail are installed and configured on the server.

== Available packages ==

Mobile API Facade is available with the following backend packages:

* ''open-xchange-mobile-api-facade''

Installation on the server varies depending on the underlying distribution, details are available in the following chapters.

=== Redhat Enterprise Linux 6 or CentOS 6 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL6|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Redhat Enterprise Linux 7 or CentOS 7 ===

Add the following repositories to your Open-Xchange yum configuration:

{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=rhelname|pc2v=RHEL7|mobile-api-facade}}

$ yum install open-xchange-mobile-api-facade

=== Debian GNU/Linux 8.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianJessie|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== Debian GNU/Linux 9.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianStretch|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== Debian GNU/Linux 10.0 ===

Add the following repositories to your Open-Xchange apt configuration:

{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=debianname|pc2v=DebianBuster|mobile-api-facade}}

$ apt-get update
$ apt-get install open-xchange-mobile-api-facade

=== SUSE Linux Enterprise Server 12 ===

{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/mobile-api-facade/VERSION|pc2n=susename|pc2v=SLE_12|mobile-api-facade}}

$ zypper ref
$ zypper install open-xchange-mobile-api-facade

= Configuration Mobile API Facade =

== Introduction ==

To be able to use the native mail apps the Mobile API Facade needs to be installed in front of the OX App Suite middleware. This document describes how to configure the Mobile API Facade.

The Mobile API Facade stores its configuration in the files <code>/opt/open-xchange/mobile-api-facade/etc/facade.properties</code> (the global configuration) and in <code>/opt/open-xchange/mobile-api-facade/etc/mobile-api-facade-config.yml</code> (hostname specific configuration). Both files support the same configuration properties as can be seen on https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.

== Connection to the OX App Suite Middleware ==

After installation of the facade package ("open-xchange-mobile-api-facade") the property <code>com.openexchange.mobile.api.facade.MiddlewareBaseUrl</code> needs to get set to the correct URL. This property needs to be explicitly configured by the administrator. It has no default value. Its possible to connect the Mobile API Facade directly to a middleware process, but this is highly discouraged. The Mobile API Facade should always connect to a middleware process through a load balancer.

An example:

com.openexchange.mobile.api.facade.MiddlewareBaseUrl=https://appsuite.example.com/appsuite/api

After this configuration the open-xchange-mobile-api-facade needs to get restarted.

== Proxy configuration ==

<Proxy balancer://oxcluster_facade>
Order Allow,Deny
Allow from all
BalancerMember http://appsuite-middleware1.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX1
BalancerMember http://appsuite-middleware2.example.com:8007 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=FOX2

ProxySet stickysession=JSESSIONID|jsessionidscolonpathdelim=On
SetEnv proxy-initial-not-pooled
SetEnv proxy-sendchunked
</Proxy>

ProxyPass /services/api-facade balancer://oxcluster_facade/services/api-facade

== Traffic compression ==

The clients need to exchange a lot of data with the facade to accomplish the task of a mail client. This traffic can be compressed. Clients add the header "Accept-Encoding: gzip,deflate" by default. For this to work the Apache web server in front of the facade needs to handle this as the facade itself is not returning compressed response bodies.

For Apache HTTPD <code>{mod_deflate}</code> needs to be enabled and the following line needs to be added to your virtual host:

AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css
text/xml application/xml text/x-js application/x-javascript application/json

== Starting/Stopping the Facade Service ==

The facade runs as its own service independent of the normal OX App Suite middleware. For this on Debian-based system it can be started with

service open-xchange-mobile-api-facade start

It can be stopped with

service open-xchange-mobile-api-facade stop

== Rereading configuration from disk ==

All configuration properties which are marked as reloadable can be configured without restarting the Mobile API Facade by using the <code>reloadconfiguration</code> utility. As the Mobile API Facade runs in its own process you need to tell <code>reloadconfiguration</code> to connect it instead of the Middleware. This can be done by:

reloadconfiguration -p 1100

== Ports ==

As the Mobile API Facade is its own process it also has its own JMX port and its own RMI port. The default JMX port is 9995 and the default RMI port is 1100. These ports needs to be explicitly specified to the command line tools using either JMX or RMI.

== Configuration of Mobile API Facade behavior ==

This can be configured in facade.properties and mobile-api-facade-config.yml.

=== Multiple host names ===

The Mobile API Facade supports multiple host names on one instance, that are configured differently. These can be configured in mobile-api-facade-config.yml. This file in YAML format. Beware that indentation is really important in YAML.

<pre>
[ host name ]:
[ properties, you want to configure ]

[ host name ]:
[ properties, you want to configure ]

...
</pre>

The allowed properties are the same as allowed in facade.properties. You can find a complete list at https://documentation.open-xchange.com/components/mobile-api-facade/config/1.8/.

=== Custom properties ===

It's possible to configure custom properties to be returned to clients. This is usefull to return special configurations to your clients. Custom properties are key/attribute values under the "customProperties" key.

Example:

<pre>
appsuite.example.com:
customProperties:
custom.specific.property: true
custom.specific.property.2: "value"
</pre>

=== Client specific configuration ===

By implementing the client specific feature the above configuration possibilities got extended. We now have to use YAML lists for each host name. This allows to add multiple different configurations to one host configuration. You can add a list of matchers in the "matches" key to a host configuration. The first "matches" entry for a given host name that matches to the given User-Agent header sent by the client will be used. Further evaluation is not done at runtime. Configuration properties need to be on the same indentation level as the "matches" key. These host configurations inherit a default configuration from the configuration in facade.properties. Otherwise they need to be complete. They don't inherit configuration properties from other places.

<pre>
[ host name ]:
- matches:
[ matchers, you want to match against ]
[ properties, you want to configure ]
- matches:
[ matchers, you want to match against ]
[ properties, you want to configure ]
...
</pre>

Example:

The iOS version supported in the beginning was iOS 9 and up. At some point in time due to technical reasons support for iOS 9 and 10 was dropped and the application supported iOS 11 and up. When you now want to update all installations on iOS 11 and up to the latest app version but leave old installations in intact you can use the force upgrade feature of the apps. Keep in mind that the matching process stops when the first match is found. If no match was found the default configuration is used.

<pre>
appsuite.example.com:
- matches:
platform: 'iOS'
osVersion: '11.0-'
brand: 'OpenXchange'
com.openexchange.mobile.api.facade.minimumClientVersion.ios: '11.2'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
- matches:
platform: 'iOS'
osVersion: '-10.99'
brand: 'OpenXchange'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
</pre>

=== Matchers ===

Several matchers are possible. All match against values in the User-Agent header.

- platform: This matcher allows it to match only for "Android" or "iOS"
- version: This matcher checks against the application version. This is not the marketing version displayed in the About screen of the application.
- osVersion: The version of the operating system on the client device
- device: This matches against the exact device model.
brand: This matches against the brand name of the app. By default this is "OpenXchange". Versions specifically branded for customers have a unique brand name.

=== Version matching ===

For the matchers 'version' and 'osVersion' we allow to match concrete versions or version ranges. When adding a matcher with a concrete version, just put the version number as string attribute after the matcher name.

<pre>
appsuite.example.com:
- matches:
platform: 'iOS'
osVersion: '11.0'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
</pre>

When matching a range we are always matching inclusive. You can either use a closed range, a range with a given start value and an end value, or an open range with either a start value or an end value. Keep in mind that to match all versions lower then '11.0' you need use a probably non-existing version number like '10.99'.

<pre>
appsuite.example.com:
- matches:
platform: 'iOS'
osVersion: '11.0-'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: true
- matches:
platform: 'iOS'
osVersion: '-10.99'
com.openexchange.mobile.api.facade.returnNonPrimaryAccounts: false
</pre>

== Debugging ==

In order to check whether installation went successful you may want to run

$ curl -v http://localhost:8007/services/api-facade/v1/version

That should return a JSON string like this:

<code>
{"version":"1.6.8","commitHash":"9e90d6072407b73c3e05b86ce724962af1a3de61","middlewareVersion":"7.10.2-Rev15"}
</code>

AppSuite:Mobile API Facade

2019-12-11T09:08:44Z

Choeger: fixed Balancer Member lines

OX as a Service Provisioning using SOAP

2019-10-17T11:34:53Z

Choeger: /* SSL-related hints */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [https://www.open-xchange.com/portfolio/ox-dovecot-pro/ OX Dovecot Pro] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2019-10-17T11:29:00Z

Choeger: /* Overview */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [https://www.open-xchange.com/portfolio/ox-dovecot-pro/ OX Dovecot Pro] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2019-10-17T11:26:23Z

Choeger: /* OXaaS specific methods */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [http://dovecot.org Dovecot] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

==== SOAP API ====

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

==== REST API ====

There's a growing number of REST APIs to access OXaaS, see https://documentation.open-xchange.com/, section ''Cloud Plugins API''.

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2019-10-17T11:21:58Z

Choeger: /* Shared domains vs ordinary domains */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [http://dovecot.org Dovecot] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains, explicit domains and ordinary domains ===

==== Ordinary domains ====

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

==== Shared domains ====

If you want to share domains between all contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])
or using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Shared-Domains REST API] (needs recent version).

==== Explicit domains ====

Recent versions support another type of domain called explicit domains. These domains must be explicitly added to contexts using the [https://documentation.open-xchange.com/components/cloudplugins/1.9.1/#tag/Explicit-Domains REST API] (needs recent version). You can add the same explicit domain to one or multiple contexts. If a context already contains an ordinary domain of the same name, it will be transformed into an explicit domain.

Note that the explicit domain feature is not available by default, it must be activated for each customer, individually.

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

AppSuite:SAML SSO Integration

2019-07-22T09:37:34Z

Choeger:

= SAML SSO Integration =

The content on this page has moved to https://documentation.open-xchange.com/latest/middleware/login_and_sessions/saml_2.0_sso.html.

Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.

OX as a Service Provisioning using SOAP

2019-07-11T07:38:21Z

Choeger: /* OXaaS specific methods */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [http://dovecot.org Dovecot] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains vs ordinary domains ===

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

If you want to share domains between multiple contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the combined values of drive and mail quota in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2019-07-11T05:52:42Z

Choeger: /* OXaaS specific methods */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [http://dovecot.org Dovecot] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains vs ordinary domains ===

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

If you want to share domains between multiple contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the same as the drive quota usage and max values in case the system has [https://documentation.open-xchange.com/latest/middleware/miscellaneous/quota.html#unified-quota unified quota] enabled.'''

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2019-07-10T13:40:59Z

Choeger: /* OXaaS specific methods */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [http://dovecot.org Dovecot] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains vs ordinary domains ===

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

If you want to share domains between multiple contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

'''Note that the mail quota usage and max values are the same as the drive quota usage and max values in case the system has unified quota enabled.'''

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2019-06-11T09:43:46Z

Choeger: /* Context creation */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [http://dovecot.org Dovecot] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains vs ordinary domains ===

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

If you want to share domains between multiple contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry topbarHover = new Entry();
topbarHover.setKey("io.ox/dynamic-theme//topbarHover");
topbarHover.setValue("#0000ff");

Entry mainColor = new Entry();
mainColor.setKey("io.ox/dynamic-theme//mainColor");
mainColor.setValue("#ff0000");

Entry linkColor = new Entry();
linkColor.setKey("io.ox/dynamic-theme//linkColor");
linkColor.setValue("#00ff00");

Entry dynThemeCapa = new Entry();
dynThemeCapa.setKey("com.openexchange.capability.dynamic-theme");
dynThemeCapa.setValue("true");

configEntries.getEntries().add(topbarHover);
configEntries.getEntries().add(mainColor);
configEntries.getEntries().add(linkColor);
configEntries.getEntries().add(dynThemeCapa);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

OX as a Service Provisioning using SOAP

2019-06-11T09:40:42Z

Choeger: /* Create a context */

= Tutorial: Provision OX as a Service using SOAP =

== Overview ==

[[OX_as_a_Service_Guide|OX as a Service]] is using the same code everybody can download and install using our
various guides. Since it is a hosted service using a reseller model, the provisioning api is using the [[Reseller_Bundle|Reseller Bundle]]
to extend the usual two administrative layers by an additional one.

Open-Xchange does also not contain a mail server in general, but requires one in order to act like a mail client. OX as a Service
is using [http://dovecot.org Dovecot] as mail server and thus extends the usual Open-Xchange provisioning capabilities by mechanisms
to manage some email specific settings.

== Open-Xchange concept of Contexts ==

In order to provision users and groups into Open-Xchange, it is important to understand, that Open-Xchange is designed
for shared hosting environments in a way that it has to serve multiple tenants, customers, domains, or however you want to
name it. In Open-Xchange, we call that a '''Context'''. A context is a sealed container for users and groups. Users in a
context can not see users of other contexts, nor can they share data with users of other contexts (with the exception of
Open-Xchange publish and subscribe functionality).

A usual scenario is to have a company, a family or in general one end customer in a context. One can also say, a context
is a domain, and usually that makes sense, since a company has one domain. However, Open-Xchange contexts are not limited
to one domain only.

== Open-Xchange concept of provisioning ==

A plain Open-Xchange installation consists of two administrative levels.

# root level, usually we call that oxadminmaster
# context level

=== oxadminmaster / root ===

The root, or oxadminmaster account is used to

* add, remove and configure filestores attached to Open-Xchange
* add, remove and configure databases attached to Open-Xchange
* add, remove and configure contexts

and change parameters like add/remove domains, change per context filesystem quota, etc.

Depending on the OX configuration, it is not able to add or remove users and groups, nor any other data within a context!

=== Context admin ===

The context admin is like an ordinary Open-Xchange user, except that it can add, remove and edit
users and groups within Open-Xchange using the provisioning API.
In addition, it inherits shared data of users, that are deleted.
'''In OX as a Service, however, the context admin cannot read, send or receive mail.'''

== OX as a Service concept of provisioning ==

As written before, plain Open-Xchange only has one root account. In a reseller scenario, that would
mean if we want resellers to be able to create contexts for their customers, we would have to hand out our
root account. Since that is not desirable, we added another layer via the [[Reseller_Bundle|Reseller Bundle]] as
mentioned earlier.

# root level, usually we call that oxadminmaster
# subadmin level / brand level
# context level

root and context level don't change, except that context level can be [[Reseller_Bundle#Restrictions|restricted]].

The subadmin account can only add, remove or configure contexts. Depending on the configuration of the
OX as a Service tenant, it can or can NOT add, remove and configure users within contexts.
Contexts created by a subadmin account can not be seen by other subadmin accounts.

=== What is a brand? ===

A brand is a customers subadmin login to the OXaaS SOAP provisioning API.

== OX as a Service specifics ==

=== Shared domains vs ordinary domains ===

In order to create a user in Open-Xchange, you have to set an email address for that user.
This will directly lead into a domain to be created into OXaaS bound to that user and its context,
if that domain does not already exists and is owned by a different context.

If you want to share domains between multiple contexts, you have to use shared domains.
Shared domains must be created in advance using the <tt>createSharedDomain</tt> method (see [[#OXaaS_specific_methods|OXaaS specific methods]])

You can use the <tt>existsMailAlias</tt> method to check for the existence of an alias before you create it.

=== Catchall accounts ===

If the feature is enabled in your contract, you can create catchall mail aliases bound to users
within contexts.

=== User permissions ===

See [[OX_as_a_Service_Provisioning_using_SOAP#Set_OXaaS_permissions|OXaaS permission]] description below.

=== User name/login uniqueness ===

Due to the architecture of OXaaS, a login/username must be unique across all created contexts. That means it is not
possible to create two "oxadmin" accounts. This limitation applies per brand.

=== Display name uniqueness ===

In contrary to the login/name of users, display names must only be unique within each context.
That is because it is used e.g. in the shared folder list of e.g. calendar, drive, contacts in OX.
Also it is used as folder name when mounting OX via WEBDAV.

It is no problem, however, to have one "Steve Smith" in one context, and another "Steve Smith” in another context.

=== No email for "oxadmin" ===

The architecture of OX as a Service does not allow the context admin to have email.

== Provisioning ==

=== OXaaS specific methods ===

The following SOAP methods are specific to OXaaS and are NOT part of the general Open-Xchange provisioning API.

{| border="1" class="wikitable"
|+ OXaaS specific SOAP calls and its authentication requirements
! Method
! Functionality
! Authentication
|-
! getQuotaUsage
| get the overall mail quota usage of all users within the given context
| Subadmin
|-
! createSharedDomain
| create a shared domain
| Subadmin
|-
! existsLogin
| check whether user login already exists. Note: a users login must be unique within all users for your subadmin account and NOT only per context!
| Subadmin
|-
! existsMailAlias
| check whether given mail alias already exists
| Subadmin
|-
! createDomainCatchall
| create a domain catchall
| Subadmin
|-
! getQuotaUsagePerUser
| get mail quota usage of the individual user within the given context
| Subadmin
|-
! listDomainCatchalls
| list all existing domain catchalls
| Subadmin
|-
! setMailQuota
| set the mail quota of the individual user within the context
| Context Admin
|-
! deleteDomainCatchall
| delete the given domain catchall
| Subadmin
|-
! getPermissions
| list given users permissions
| Subadmin
|-
! enablePermissions
| enable provided permissions for given user
| Subadmin
|-
! disablePermissions
| enable provided permissions for given user
| Subadmin
|-
! setExpiryDate
| store expiry date for the given user
| Context Admin
|-
! getExpiryDate
| get expiry date stored for user
| Context Admin
|-
! deleteExpiryDate
| delete the expiry date stored in the given user
| Context Admin
|-
! getExpiredUsers
| retrieve list of expired users
| Subadmin
|-
! getMailQuota
| get the mail quota of the individual user within the context
| Subadmin
|-
! setPasswordHash
| directly store provided pwHash into userPassword attribute of matching ldap entry. Note: Input will be validated against valid mechanisms.
| Context Admin
|}

The WSDL source file for these methods contain documentation for each of the calls and parameters.
You can download it here: http://software.open-xchange.com/products/appsuite/doc/oxasservice/OXaaSService.wsdl

=== OX Core Provisioning API ===

The core provisioning API consists of four namespaces:

# Context management
# User management
# Group management
# Resource management

Some of these namespaces share the same data structures such as <tt>Credentials</tt>, <tt>Context</tt> and <tt>User</tt>.

[[File:provisioning-core.png|1000 px]]

=== Reference implementation ===

The reference implementation of the European OX as a Service system can be found in the {{APSPackage|name=OX as a Service}} APS package
for [http://www.odin.com/products/automation/ Odin Service Automation].

=== Workflow ===

==== Subadmin credentials ====

The first requirement is to get subadmin credentials for your company. Please follow the steps
[[OX_as_a_Service_Guide#How_to_become_a_customer.3F|documented here]] to get such an account.

Together with the login and password you will also retrieve the provisioning URL to be used by
all SOAP requests. In addition, it is required that you give us a list of ip addresses or network(s)
that should be allowed to access the provisioning system.

==== WSDL files ====

Just point your browser to the provisioning URL you got from us. You will find some services listed there.
You will need the following services from that list:

; https://hostname/webservices/OXaaSService?wsdl: OX as a Service specific functions
; https://hostname/webservices/OXResellerContextService?wsdl: Context management
; https://hostname/webservices/OXResellerUserService?wsdl: User management

and optionally

; https://hostname/webservices/OXResellerGroupService?wsdl: Group management
; https://hostname/webservices/OXResellerResourceService?wsdl: Resource management

==== SOAP API documentation ====

The general SOAP API documentation can be found at this URL:
http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html

That document contains links to the Javadoc documentation for the RMI api, but
that is more or less the same as the SOAP API.

In addition, there's the general, non OXaaS specific [[Open-Xchange_Provisioning_using_SOAP|wiki page]].

==== Create a context ====

Once you have the credentials in place, you are ready to create your first context.

Creating a context requires to create the first user in that context, that is the context admin, see above.

Mandatory settings for a context are

; name: name of the context
; quota: file quota in MB for that context ('''Note:''' that is file, not mail!)
; taxonomy: must be set to the login of your subadmin account, see below

'''Important:''' In OXaaS, the name of the context must always start with your subadmin login with an underscore appended. E.g. when
your subadmin login is <tt>johndoe</tt>, the all your context names must start with <tt>johndoe_</tt>!

Optional settings

; mainColor: io.ox/dynamic-theme//mainColor
; linkColor: io.ox/dynamic-theme//linkColor
; for further theme parameters, check https://documentation.open-xchange.com/latest/ui/theming/dynamic-theming.html

; id: A numerical id bound to the context. When you create a context, this id will be generated. You will need that later when you manage users. The id can be looked up via the context name.

===== userAttributes =====

The settings brandtaxonomy and the other optional settings except id are part of the userAttributes SOAP field.
All other settings can easily be set via simple SOAP settings. userAttributes is a hash that contains some settings
that are not available in all setups of Open-Xchange. It allows to extend Open-Xchange functionality dynamically like
done in OXaaS.

The hash looks like this:

userAttributes => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

somevalue can be an array again, e.g.:

somevalue => entries => EntryArray

with EntryArray :=

[
{ key => "somekey"
value => somevalue },
{ key => "someotherkey"
value => someothervalue },
...
]

and so on

Example dump using perls <code>Data::Dumper</code>:

<syntaxhighlight lang="perl">
'userAttributes' => {
'entries' => [
{
'value' => {
'entries' => [
{
'value' => '#0000ff',
'key' => 'io.ox/dynamic-theme//topbarHover'
},
{
'value' => '#ff0000',
'key' => 'io.ox/dynamic-theme//linkColor'
},
{
'value' => '#00ff00',
'key' => 'io.ox/dynamic-theme//mainColor'
},
{
'value' => 'true',
'key' => 'com.openexchange.capability.dynamic-theme'
} ]
},
'key' => 'config'
},
{
'value' => {
'entries' => {
'value' => 'johndoe',
'key' => 'types'
}
},
'key' => 'taxonomy'
}
]
},
</syntaxhighlight>

===== Admin User =====

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,

====== Timezones ======

To get a list of all available timezones, you can run this short Java program:

<syntaxhighlight lang="java">
import java.util.TimeZone;

public class AllTimeZones {
public static void main(String[] args) {
for(final String zone : TimeZone.getAvailableIDs() ) {
System.out.println(zone);
}
}

}
</syntaxhighlight>

====== Languages ======

This is the list of currently supported languages in OXaaS:

ja_JP
de_DE
es_ES
es_MX
fr_FR
it_IT
nl_NL
pl_PL
zh_TW
en_US
en_GB

==== Create users ====

Creating users requires the following parameters

; name: login name of the context admin
; password: password
; email: email address of the context admin
; displayname: displayname (usually surname givenname)
; surname: surname
; givenname: given name
; lang: language, e.g. en_GB, en_US, de_DE, ...
; timezone: Java timezone such as Europe/Berlin,
; moduleaccess: the module access combination name
; mailquota: the mail quota of the user in MB

Timezones and languages like documented earlier.

Valid values for moduleaccess are:

* webmail_plus
* groupware_standard
* groupware_advanced
* groupware_premium

Other settings are not supported.

===== userAttributes =====

It might be required you have to set some specific attributes per user like the Edition Type as
done by the OXaaS APS package.

There's a choice of 7 different edition types:

; webmail: bound to webmail_plus
; basic: bound to groupware_standard
; advanced: bound to groupware_advanced
; pro: bound to groupware_premium
; pro_m: bound to groupware_premium
; pro_l: bound to groupware_premium
; pro_xl: bound to groupware_premium

which can be set within each users oxaas_edition_type within a tree oxaas:

'userAttributes' => {
'entries' => {
'key' => 'oxaas',
'value' => {
'entries' => {
'key' => 'oxaas_edition_type',
'value' => 'pro_l'
}
}
}
}

see [[#Standalone_example:_createOXaaSUser|createuser example script]]

===== Create the user in Open-Xchange =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>

Use the <code>OXResellerUserService->createByModuleAccessName</code> to create users.

'''Note:''' Although there are three create methods in the SOAP user service API, you have to use the method <code>createByModuleAccessName</code>
and specify one of the names listed above.

===== Set mail quota =====

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use the <code>OXaaSService->setMailQuota</code> call to set the mail quota for the user created above.

===== Set OXaaS permissions =====

====== Explanation ======

The OXaaS permissions allow to enable or disable a certain set of features.
Currently, the following permissions are available:

{| border="1" class="wikitable"
|+ OXaaS permissions
! Permission
! Description
|-
! SEND
| User is allowed to send mail
|-
! RECEIVE
| User is allowed to receive mail
|-
! MAILLOGIN
| User can login using IMAP from external; webmail is not affected
|-
! WEBLOGIN
| User can login to OX webmail.
|}

The permission names are case insensitive.
The WEBLOGIN permission is the same as the [http://software.open-xchange.com/products/appsuite/doc/RMI/admin-core/com/openexchange/admin/rmi/dataobjects/User.html#setMailenabled%28java.lang.Boolean%29 <tt>Mailenabled</tt>] permission in the user data of the Open-Xchange core api. The permission
OXaaS api provides another way to enable/disable it.

* Use the name and password of the context admin user of the context you created earlier and define
a Credentials object.
* Find the numerical id of the context e.g. in using <code>OXResellerContextService->getData(name="contextname")</code>
* Find the numerical id of the user either by using <code>OXResellerUserService->getData(name="username")</code> or use/store the return value of <code>OXResellerUserService->createByModuleAccessName</code>

Use one of <code>OXaaSService->enablePermissions</code>, <code>OXaaSService->disablePermissions</code> or <code>OXaaSService->getPermissions</code>
to change or retrieve permissions. Permissions must always be provided as an array of 1 or more permissions.

=== SOAP provisioning feature matrix ===

(WIP)

The table below shows what method(s) to use and what to set in order to configure the different feature sets.

The value in the row ''Module Access Name'' must be given as a parameter to <code>OXResellerUserService->changeByModuleAccessName</code>
or <code>OXResellerUserService->createByModuleAccessName</code>.

The values in the row ''Capabilities'' must be given as parameters to the <code>userAttributes</code> member of the <code>User</code> object that
should be changed and then passed to <code>OXResellerUserService->change</code> or <code>OXResellerUserService->createByModuleAccessName</code>.

'''Note: <code>OXResellerUserService->changeByModuleAccessName</code> does NOT change these capabilities!'''

{| border="1" class="wikitable"
|+ Provisioning Feature Matrix
! Feature
! Module Access Name
! Capabilities ''(mandatory values in bold, others are optional)''
|-
! Web Mail
| webmail_plus
| <tt>com.openexchange.capability.drive = '''false'''</tt> <tt>com.openexchange.capability.document_preview = '''false'''</tt> <tt>com.openexchange.capability.spreadsheet = '''false'''</tt> <tt>com.openexchange.capability.text = '''false'''</tt> <tt>com.openexchange.capability.presenter = '''false'''</tt> <tt>com.openexchange.capability.remote_presenter = '''false'''</tt> <tt>com.openexchange.capability.guard = '''false'''</tt> <tt>com.openexchange.capability.guard-mail = '''false'''</tt> <tt>com.openexchange.capability.guard-drive = '''false'''</tt>
|-
! Basic
| <tt>groupware_standard</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Advanced
| <tt>groupware_advanced</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = true/false</tt> <tt>com.openexchange.capability.spreadsheet = true/false</tt> <tt>com.openexchange.capability.text = true/false</tt> <tt>com.openexchange.capability.presenter = true/false</tt> <tt>com.openexchange.capability.remote_presenter = true/false</tt> <tt>com.openexchange.capability.guard = true/false</tt> <tt>com.openexchange.capability.guard-mail = true/false</tt> <tt>com.openexchange.capability.guard-drive = true/false</tt>
|-
! Pro
| <tt>groupware_premium</tt>
| <tt>com.openexchange.capability.drive = '''true'''</tt> <tt>com.openexchange.capability.document_preview = '''true'''</tt> <tt>com.openexchange.capability.spreadsheet = '''true'''</tt> <tt>com.openexchange.capability.text = '''true'''</tt> <tt>com.openexchange.capability.presenter = '''true'''</tt> <tt>com.openexchange.capability.remote_presenter = '''true'''</tt> <tt>com.openexchange.capability.guard = '''true'''</tt> <tt>com.openexchange.capability.guard-mail = '''true'''</tt> <tt>com.openexchange.capability.guard-drive = '''true'''</tt>
|}

=== List of available capabilities (incomplete) ===

These features are controlled by the [[ConfigCascade]].

For drive and documents the following settings are responsible:

; OX Drive :
<tt>com.openexchange.capability.drive = true/false</tt>

; OX Docs :
<tt>com.openexchange.capability.document_preview = true/false</tt> 
<tt>com.openexchange.capability.spreadsheet = true/false</tt> 
<tt>com.openexchange.capability.text = true/false</tt> 
<tt>com.openexchange.capability.presentation = true/false</tt> 
<tt>com.openexchange.capability.remote_presenter = true/false</tt> 
<tt>com.openexchange.capability.guard-docs = true/false</tt>

; OX Guard :
<tt>com.openexchange.capability.guard = true/false</tt> 
<tt>com.openexchange.capability.guard-mail = true/false</tt> 
<tt>com.openexchange.capability.guard-drive = true/false</tt> 

Using [[OX_as_a_Service_Provisioning_using_SOAP#Standalone_example:_createOXaaSContext|this perl example]]:

e.g. this

logouturl => {
setting => "io.ox/core//customLocations/logout",
value => "logouturl"
}

is setting the ConfigCascade setting <tt>io.ox/core//customLocations/logout</tt> to the string “logouturl"

io.ox/core//customLocations/logout = "logouturl"

adding

oxdrive => {
setting => "com.openexchange.capability.drive",
value => "true"
}

in that example would turn on drive.

== Code Examples ==

=== Java ===

==== Generating the SOAP client ====

Since Open-Xchange is using [http://cxf.apache.org/ Apache CXF] for SOAP, we recommend to use the <tt>wsdl2java</tt>
code generator from that package.

The Open-Xchange SOAP services are divided into multiple parts, which makes the code generation a little
complex.

In OXaaS we need at least three services in order to create contexts and users:

* OXResellerContextService
* OXResellerUserService
* OXaaSService

The shell script below generates the stubs of these three services into the directory defined in the <tt>CODEBASE</tt>
variable. In addition, you have to set <tt>WSDLURL</tt> to point it to the provisioning URL you will get from us as
mentioned [[#Subadmin_credentials|earlier]].

Note: when running against a DEV container without valid SSL certs (e.g. self-signed SSL certs), it is required to add the servers cert into your java keystore first:

# Get the cert e.g. by <code>openssl s_client -connect my.oxaas.webservices.host.net:443</code> (the part between BEGIN CERTIFICATE and END CERTIFICATE) or by exporting from a web browser. Put it in a file named for example <code>my.oxaas.webservices.host.net.crt</code>.
# Import it in a custom TrustStore. Assign a password; in this example we assume "secret": <code>keytool -import -trustcacerts -alias my.oxaas.webservices.host.net -keystore my.oxaas.webservices.host.net.jks -file my.oxaas.webservices.host.net.crt -storetype JKS</code>
# Supply it to the JVM by patching the CXF wsdl2java script (e.g. <code>/opt/apache-cxf-3.1.14/bin/wsdl2java</code>) and add the following arguments: <code>-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS</code>

Copy&paste the shell script below into a file and run it using the <tt>bash</tt> shell. Warning: the script assumes the CODEBASE target lives in its own dedicated ecplise project, and executes a <code>rm -rf $CODEBASE</code> for a clean start. For other usecases (shared eclipse project, etc), please adjust to your needs / be careful!

<syntaxhighlight lang="bash">
# 1. download apache-cxf tarball, extract it and "cd" into the directory, e.g.
# tar zxvpf apache-cxf-3.1.10.tar.gz; cd apache-cxf-3.1.10
# NOTE: cxf versions 3.0 do NOT work ootb with java-1.8!
# 2. change variables CODEBASE, JAVA_HOME and WSDLURL
# 3. run this script "bash oxaas-wsdl2java"
export JAVA_HOME="/usr/lib/jvm/java-1.8.0-openjdk-amd64/"
CODEBASE="/home/oxgit/workspace/OXaaSJClient/src"
WSDLURL="https://youroxaashost/webservices"

rm -rf $CODEBASE
frontend=jaxws21
dbinding=jaxb

JAXBTMP=/tmp/jaxb$$.xml
rm -f $JAXBTMP
cat<<EOF > $JAXBTMP
<jaxb:bindings version="2.1"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<jaxb:globalBindings generateElementProperty="false"/>
</jaxb:bindings>
EOF

pname="com.openexchange.oxaas.context"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerContextService?wsdl

pname="com.openexchange.oxaas.user"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.reseller.admin.openexchange.com=${pname}" \
-p "http://dataobjects.rmi.reseller.admin.openexchange.com/xsd=${pname}.reseller.rmi.dataobjects" \
-p "http://dataobjects.soap.reseller.admin.openexchange.com/xsd=${pname}.reseller.soap.dataobjects" \
-p "http://dataobjects.soap.admin.openexchange.com/xsd=${pname}.soap.dataobjects" \
-p "http://dataobjects.rmi.admin.openexchange.com/xsd=${pname}.rmi.dataobjects" \
-p "http://exceptions.rmi.admin.openexchange.com/xsd=${pname}.rmi.exceptions" \
-p "http://rmi.java/xsd=${pname}.java.rmi" \
-p "http://io.java/xsd=${pname}.java.io" \
${WSDLURL}/OXResellerUserService?wsdl

pname="com.openexchange.oxaas.extra"
bin/wsdl2java -databinding $dbinding -frontend $frontend -client -impl -d $CODEBASE -keep -b $JAXBTMP \
-p "http://soap.oxaas.admin.openexchange.com/=${pname}" \
${WSDLURL}/OXaaSService?wsdl

rm -f $JAXBTMP
</syntaxhighlight>

When you generate the code into an existing eclipse project, you should have three main packages as shown in
the image below

[[File:OXaaSSOAPClientEclipse.png]]

==== Example Client ====

In the following example, the context creation and the user creation is separated into different
programs.

To summarize some essential requirements from the example below:

* The name of each context you create must start with your subadmin name followed by an underscore <tt>_</tt>
* You must set the userAttribute <tt>taxonomy</tt> at least
* The context admin user must get the <tt>groupware_premium</tt> access permission

===== Build / run instructions =====

====== Eclipse ======

We assume, you have created the Java client stub(s) as documented above and have it as a separate eclipse project. The individual clients given below are assumed to live in a different ecplise project which references the Java client stubs in their classpath.

====== Command Line ======

For maximum simplicity let's assume you use the source files given below without the <code>package</code> statement. Put them in an <code>examples/</code> subdirectory.

Let's assume furthermore you created the Java client stubs in a different directory, e.g. <code>codebase/</code>.

Change into that directory to compile all the Java stub files

cd codebase/
find . -name \*.java | xargs javac

Back in the working directory where the source files given below are created, you can compile / run them like

cd ../examples/
javac -cp ../codebase MyContextClientExample.java
java -cp .:../codebase MyContextClientExample

====== SSL-related hints ======

When working against a dev machine with self-signed certs, the same certificate trust related options are required as explained above for the <code>wsdl2java</code> script (with the same TrustStore and password):

-Djavax.net.ssl.trustStore=my.oxaas.webservices.host.net.jks -Djavax.net.ssl.trustStorePassword=secret -Djavax.net.ssl.trustStoreType=JKS

It might be additionally helpful to enable SSL debug output: <code>-Djavax.net.debug=ssl</code>

As of now (2017-11) there is a flaw in the generated WSDL that it references HTTP SOAP addresses even when using HTTPS. This results in client programs trying to access the API via plain HTTP even after a successful SSL handshake and fetching the WSDL via HTTPS. This is bad as SOAP frames travel the network with credentials included in plain text.

A possible workaround for the time being is to forcefully rewrite the protocol part of the different port urls into https with something like:

After initializing the contextport using ...

<syntaxhighlight lang="java">
OXResellerContextServicePortType contextport =
contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
</syntaxhighlight>

... add the following code:

<syntaxhighlight lang="java">
// insert in your imports section:
// import javax.xml.ws.BindingProvider;
((BindingProvider)contextport).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
((String)((BindingProvider)contextport).getRequestContext()
.get(BindingProvider.ENDPOINT_ADDRESS_PROPERTY))
.replaceAll("^http:", "https:"));
</syntaxhighlight>

Similar adjustments are required for <code>userport</code> and <code>oxaasport</code>, where they occur.

===== Context creation =====

The example below shows how to create a context in OXaaS.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.ContextExistsExceptionException;
import com.openexchange.oxaas.context.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.context.Delete;
import com.openexchange.oxaas.context.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.context.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.context.InvalidDataExceptionException;
import com.openexchange.oxaas.context.NoSuchContextExceptionException;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.context.RemoteExceptionException;
import com.openexchange.oxaas.context.StorageExceptionException;
import com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.context.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.context.soap.dataobjects.Entry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPMapEntry;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMap;
import com.openexchange.oxaas.context.soap.dataobjects.SOAPStringMapMap;
import com.openexchange.oxaas.context.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerContextService
*
* Create a context
*
*/
public class MyContextClientExample {

private static final QName SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User oxadmin = new User();

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();

creds.setLogin(subadminname);
creds.setPassword(subadminpw);

SOAPMapEntry taxonomy = new SOAPMapEntry();
taxonomy.setKey("taxonomy");
SOAPStringMap taxtypeval = new SOAPStringMap();
Entry taxtypeent = new Entry();
taxtypeent.setKey("types");
taxtypeent.setValue(subadminname);
taxtypeval.getEntries().add(taxtypeent);
taxonomy.setValue(taxtypeval);

SOAPMapEntry config = new SOAPMapEntry();
config.setKey("config");
SOAPStringMap configEntries = new SOAPStringMap();

Entry selectionColor = new Entry();
selectionColor.setKey("io.ox/dynamic-theme//selectionColor");
selectionColor.setValue("#0000ff");

Entry frameColor = new Entry();
frameColor.setKey("io.ox/dynamic-theme//frameColor");
frameColor.setValue("#ff0000");

Entry iconColor = new Entry();
iconColor.setKey("io.ox/dynamic-theme//iconColor");
iconColor.setValue("#00ff00");

configEntries.getEntries().add(selectionColor);
configEntries.getEntries().add(frameColor);
configEntries.getEntries().add(iconColor);
config.setValue(configEntries);

SOAPStringMapMap userattrs = new SOAPStringMapMap();
userattrs.getEntries().add(taxonomy);
userattrs.getEntries().add(config);

ctx.setName(ctxname);
ctx.setMaxQuota(10000l);
ctx.setUserAttributes(userattrs);

final String adminEmail = "oxadmin@example.com";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
oxadmin.setName(ctxadmname);
oxadmin.setPassword(ctxadmpw);
oxadmin.setDisplayName("OX Admin");
oxadmin.setSurName("OX");
oxadmin.setGivenName("Admin");
oxadmin.setPrimaryEmail(adminEmail);
oxadmin.setEmail1(adminEmail);
oxadmin.setDefaultSenderAddress(adminEmail);
oxadmin.setLanguage("en_US");
oxadmin.setTimezone("Europe/Berlin");

try {
ResellerContext ret = contextport.createModuleAccessByName(ctx, oxadmin, "groupware_premium", creds, null);
System.out.println("created context with id=" + ret.getId());

System.out.println("existing contexts:");
List<ResellerContext> allctxs = contextport.listAll(creds);
for(final ResellerContext c : allctxs) {
System.out.println(c.getName() + " with id=" + c.getId());
}

System.in.read();

System.out.println("deleting created context again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
contextport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (ContextExistsExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== User creation =====

The client below utilizes all SOAP services we have created so far.

The essential parts of the code are

* use OXResellerContextService to find out the ID of the context you want to create users
* create users using OXResellerUserService
* use one of the moduleaccess values as documented [[#Create_users|earlier]]
* use setMailQuota from OXaaSService to set each users mail quota individually
* use existsLogin from OXaaSService to check in advance of a login already exists

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.io.IOException;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.ExistsLoginFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.extra.SetMailQuotaFaultException;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.Delete;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class MyUserClientExample {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();
User auser = new User();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

final String userEmail = "auser@example.com";
auser.setName("auser");
auser.setPassword("secret");
auser.setDisplayName("My User");
auser.setSurName("My");
auser.setGivenName("User");
auser.setPrimaryEmail(userEmail);
auser.setEmail1(userEmail);
auser.setDefaultSenderAddress(userEmail);
auser.setLanguage("en_US");
auser.setTimezone("Europe/Berlin");

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

// create the user via OXResellerUserService
User ret = userport.createByModuleAccessName(ctx, auser, "groupware_premium", creds);
System.out.println("created user with id=" + ret.getId());

// set mail quota for that user using OXaaSService
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(ctxadmname);
oxaasCtxCreds.setPassword(ctxadmpw);
oxaasport.setMailQuota(ctxRet.getId(), ret.getId(), 1000l, oxaasCtxCreds);

// check whether the login for the user has been created within my subadmin namespace
// NOTE: this check should be used beforehand usually: check whether login exists and then create it if not
com.openexchange.oxaas.extra.Credentials oxaasAdminCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasAdminCreds.setLogin(subadminname);
oxaasAdminCreds.setPassword(subadminpw);
if( oxaasport.existsLogin("auser", oxaasAdminCreds) ) {
System.out.println("all ok, user login has been created");
}

System.in.read();

System.out.println("deleting created user again");
Delete del = new Delete();
del.setAuth(creds);
del.setCtx(ctx);
del.setUser(ret);
userport.delete(del);
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (IOException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (SetMailQuotaFaultException e) {
e.printStackTrace();
} catch (ExistsLoginFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Email (alias) management =====

The next example shows how to manage email aliases and shared domains.
The essential information is:

* if you want to change the email address of a user, you have to add the new address to the list of aliases
* when you want to change individual settings of a user, only send the changed settings

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import java.util.List;
import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateSharedDomainFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;
import com.openexchange.oxaas.user.Change;
import com.openexchange.oxaas.user.DatabaseUpdateExceptionException;
import com.openexchange.oxaas.user.DuplicateExtensionExceptionException;
import com.openexchange.oxaas.user.InvalidCredentialsExceptionException;
import com.openexchange.oxaas.user.InvalidDataExceptionException;
import com.openexchange.oxaas.user.NoSuchContextExceptionException;
import com.openexchange.oxaas.user.NoSuchUserExceptionException;
import com.openexchange.oxaas.user.OXResellerUserService;
import com.openexchange.oxaas.user.OXResellerUserServicePortType;
import com.openexchange.oxaas.user.RemoteExceptionException;
import com.openexchange.oxaas.user.StorageExceptionException;
import com.openexchange.oxaas.user.reseller.soap.dataobjects.ResellerContext;
import com.openexchange.oxaas.user.rmi.dataobjects.Credentials;
import com.openexchange.oxaas.user.soap.dataobjects.User;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSAliasManagement {

private static final QName USER_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerUserService");
private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String ctxadmname = "oxadmin";
final String ctxadmpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

Credentials creds = new Credentials();
ResellerContext ctx = new ResellerContext();

OXResellerUserService userservice = new OXResellerUserService(OXResellerUserService.WSDL_LOCATION, USER_SERVICE_NAME);
OXResellerUserServicePortType userport = userservice.getOXResellerUserServiceHttpSoap12Endpoint();
OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

creds.setLogin(ctxadmname);
creds.setPassword(ctxadmpw);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);
ctx.setId(ctxRet.getId());

/*
* now we want to add an alias to the user "auser"
*/
User auser = new User();
auser.setName(userlogin);
User ret = userport.getData(ctx, auser, creds);
List<String> aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
// now add another one
aliases.add("sales@example.com");

// we also want to add an alias within a shared domain
com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);
/*
* Note: we can run this method as often as we want, it will ONLY return an error in case we want to add a shared domain
* that is already bound to another subadmin/customer
*/
oxaasport.createSharedDomain("shared.net", oxaasCtxCreds);
aliases.add("me@shared.net");

// store changes
// we need to created a clean user instance since we cannot just store back the returned user
User changeduser = new User();
changeduser.setId(ret.getId());
changeduser.getAliases().addAll(aliases);
Change change = new Change();
change.setAuth(creds);
change.setCtx(ctx);
change.setUsrdata(changeduser);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);

/*
* now changing the users email address:
* to do that, we have to do the following:
* 1. add the new email address to the aliases, if not yet present
* 2. change the email address in email1, defaultsenderaddress and primarymail
*
*/
String newaddress = "boss@mydomain.com"; // introduce another domain, not shared
changeduser = new User();
changeduser.setId(ret.getId());
changeduser.setEmail1(newaddress);
//reuse change from above
change.setUsrdata(changeduser);
try {
// this will throw an error since the new address is not in the aliases
userport.change(change);
} catch (Exception e) {
System.out.println("ERROR: " + e.getMessage());
}

// now add the new address to the aliases and try again
aliases = ret.getAliases();
aliases.add(newaddress);
changeduser.getAliases().addAll(aliases);
userport.change(change);

// control the result
ret = userport.getData(ctx, auser, creds);
aliases = ret.getAliases();
// list all mail aliases of that user
System.out.println("User has the following alias(es):" + aliases);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (InvalidDataExceptionException e) {
e.printStackTrace();
} catch (NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (DatabaseUpdateExceptionException e) {
e.printStackTrace();
} catch (InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (RemoteExceptionException e) {
e.printStackTrace();
} catch (NoSuchUserExceptionException e) {
e.printStackTrace();
} catch (StorageExceptionException e) {
e.printStackTrace();
} catch (CreateSharedDomainFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

===== Catchall account management =====

The next example shows how to manage catchall accounts.
Please take into account that this is not necessarily enabled for your account.

<syntaxhighlight lang="java">
package com.openexchange.oxaas.myclient;

import javax.xml.namespace.QName;
import com.openexchange.oxaas.context.OXResellerContextService;
import com.openexchange.oxaas.context.OXResellerContextServicePortType;
import com.openexchange.oxaas.extra.CreateDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DeleteDomainCatchallFaultException;
import com.openexchange.oxaas.extra.DomainCatchall;
import com.openexchange.oxaas.extra.ListDomainCatchallsFaultException;
import com.openexchange.oxaas.extra.OXaaSService;
import com.openexchange.oxaas.extra.OXaaSService_Service;

/*
* Example SOAP client for OXaaS OXResellerUserService
*
* Create users in a context
*
*/
public class OXaaSCatchAllManagement {

private static final QName CONTEXT_SERVICE_NAME = new QName("http://soap.reseller.admin.openexchange.com", "OXResellerContextService");
private static final QName OXAAS_SERVICE_NAME = new QName("http://soap.oxaas.admin.openexchange.com/", "OXaaSService");

public static void main(String[] args) {
final String subadminname = "mysubadmin";
final String subadminpw = "secret";
final String userlogin = "auser";
final String ctxname = subadminname + "_myctx";

OXResellerContextService contextservice = new OXResellerContextService(OXResellerContextService.WSDL_LOCATION, CONTEXT_SERVICE_NAME);
OXResellerContextServicePortType contextport = contextservice.getOXResellerContextServiceHttpSoap11Endpoint();
OXaaSService_Service oxaasservice = new OXaaSService_Service(OXaaSService_Service.WSDL_LOCATION, OXAAS_SERVICE_NAME);
OXaaSService oxaasport = oxaasservice.getOXaaSServiceSOAP();

// We need to use the ResellerContextService SOAP client stub to retrieve the context id
com.openexchange.oxaas.context.rmi.dataobjects.Credentials ctxCreds = new com.openexchange.oxaas.context.rmi.dataobjects.Credentials();
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxCtx = new com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext();
ctxCreds.setLogin(subadminname);
ctxCreds.setPassword(subadminpw);
ctxCtx.setName(ctxname);

try {
// we only have the name of the context, so we need to retrieve its id, first using ResellerContextService
com.openexchange.oxaas.context.reseller.soap.dataobjects.ResellerContext ctxRet = contextport.getData(ctxCtx, ctxCreds);

com.openexchange.oxaas.extra.Credentials oxaasCtxCreds = new com.openexchange.oxaas.extra.Credentials();
oxaasCtxCreds.setLogin(subadminname);
oxaasCtxCreds.setPassword(subadminpw);

/*
* Note: this will throw an error
* oxaas_catchall_domain capability not available for context XXX, user YYY in brand ZZZ
* unless you have domain catchall in your contract
*/
oxaasport.createDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);

for(final DomainCatchall dc : oxaasport.listDomainCatchalls(ctxRet.getId(), oxaasCtxCreds) ) {
System.out.println("Catchall account for domain " + dc.getDomain() + " is " + dc.getLogin());
}

// cleanup
oxaasport.deleteDomainCatchall(ctxRet.getId(), "example.com", userlogin, oxaasCtxCreds);
} catch (com.openexchange.oxaas.context.InvalidDataExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.NoSuchContextExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.DuplicateExtensionExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.InvalidCredentialsExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.RemoteExceptionException e) {
e.printStackTrace();
} catch (com.openexchange.oxaas.context.StorageExceptionException e) {
e.printStackTrace();
} catch (ListDomainCatchallsFaultException e) {
e.printStackTrace();
} catch (DeleteDomainCatchallFaultException e) {
e.printStackTrace();
} catch (CreateDomainCatchallFaultException e) {
e.printStackTrace();
}
}

}
</syntaxhighlight>

=== Perl ===

==== Standalone example: createOXaaSContext ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSContext.pl

==== Standalone example: createOXaaSUser ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/createOXaaSUser.pl

==== Standalone example: changeOXaaSUserPermissions ====

http://software.open-xchange.com/products/appsuite/doc/oxasservice/changeOXaaSUserPermissions.pl

==== OXaas APS(1.2) package ====

Just download the APS package as mentioned [[#Reference_implementation|here]]. When you extract the zip file, you will find
the perl code within the directory <tt>scripts</tt>.

;OXSOAP.pm: SOAP Wrapper functions
;configure-alias.pl: Mail alias management
;configure-catchall.pl: Catchall mail alias management
;configure-mbox.pl: User management
;configure.pl: Context management
;verify-account.pl: check for login existence (existsLogin)
;verify-catchall.pl: check for catchall existence
;verify-shared.pl: shared mail alias checks

AppSuite:Introduction to the HTTP API

2019-05-02T05:58:30Z

Choeger:

== Introduction ==

The content on this page has moved to https://documentation.open-xchange.com/components/middleware/http/latest/index.html.

Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.

AppSuite:CrossContextDatabase

2018-08-30T11:17:36Z

Choeger:

<div class="title">Cross-context database</div>

{{VersionFrom|7.8.0}}

__TOC__

For storing data across context boundaries, a so called "global" database is used by the server. For example, such shared data could be information about guest users or data for registered OAuth applications. This article gives an overview about the basic concepts and how to setup a global database.

== Register databases ==

As a prerequisite, a global database needs to be registered in the Open-Xchange server's configuration database. At the storage layer, global databases are handled just like the ordinary <tt>context</tt> databases storing all the existing groupware data. Therefore, the same underlying technologies can be used for replication like master/slave- or Galera-based setups, as well as registering additional database pools for sharding in very large installations.

So, much similar to the groupware databases that store context-internal data, a new global database can be registered using the <tt>registerdatabase</tt> commandline tool. To prevent the registered database being picked up for groupware data, set the <tt>maxunit</tt> argument to <tt>0</tt>:

$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal --hostname localhost --dbuser openexchange --dbpasswd db_password --master true --maxunit 0
database 8 registered

Remember the returned database identifier, <tt>8</tt> in the above example, we'll need it at a later stage.

Optionally, in case a database slave should be added, you can register it afterwards by specifying the database identifier as <tt>masterid</tt> like follows:

$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password --name oxglobal_slave --hostname slave_host --dbuser openexchange --dbpasswd db_password --master false --maxunit 0 --masterid=8
database 9 registered

For smaller or test environments, it's also possible to re-use a previously registered groupware database for cross-context data, i.e. any database marked as <tt>master</tt> by the <tt>listdatabase</tt> utility may be used. Please note that all cross-context data is not accounted when calculating the database weight during context creation.

== Context Groups ==

As already mentioned, data inside the global database is shared between and available to all contexts in the installation. For setups serving multiple different "brands" or "domains", this may not be the desired behavior, so that an additional level of data separation is needed for cross-context data. Therefore, one or more contexts can be classified into a specific "group". The association with the group is done by assigning the property <tt>com.openexchange.context.group</tt> to a context via config cascade. A context may only be part of one group, contexts without group association automatically fall into the "default" group.

As an example, a hoster is selling his hosted e-mail services under two different brands, called "Clever Hosting" and "Smart Hosting". Each customer that registered an account at "Clever Hosting" now is put into the context group "clever_hosting" by setting the property <tt>com.openexchange.context.group</tt> at any level of the config cascade, e.g. during provisioning when creating the context like:

$ /opt/open-xchange/sbin/createcontext [...] --config/com.openexchange.context.group=clever_hosting

Or, if you already tagged your contexts with different taxonomy types (like <tt>clever</tt> and <tt>smart</tt> in our example), the assignment to a context group can also be achieved at "ContextSet" level inside an <tt>.yml</tt>-file of your <tt>contextSets</tt> definitions:

<pre>
clever_group:
withTags: clever
com.openexchange.context.group: clever_hosting
ui/product/name: "Clever Hosting"
[...]

smart_group:
withTags: smart
com.openexchange.context.group: smart_hosting
ui/product/name: "Smart Hosting"
[...]
</pre>

In the global database, the context group identifier serves as differentiating key for various data. For example, data of a guest user that was invited to a share in one context of a group can be used throughout all other contexts of the same group. Or, there may be a different set of registered OAuth applications available for each context group. Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. The next chapter describes the global database configuration file in more detail.

== Configure databases ==

Global databases are defined in the configuration file <tt>globaldb.yml</tt>. It mainly serves the purpose to map registered global databases to context groups. In case no advanced context grouping is necessary, e.g. because there's only a single brand in the installation, it's sufficient to supply the identifier of the previously registered master database, see [[#Register databases|Register databases]] above, inside the <tt>default</tt> section of the configuration file. For example, if the identifier of the global database master is <tt>8</tt>, the section would look like:

<pre>
default:
groups: [default]
id: 8
</pre>

This would lead to all cross-context data being stored at this database, assigning distinguished context groups as described in [[#Context Groups|Context Groups]] is not required.

If there are multiple context groups, those can be directed to a specific global database by adding their names to the <tt>groups</tt> property of a configuration section. For example, if the groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> should use database <tt>8</tt>, too, one could define:

<pre>
default:
groups: [default,smart_hosting,clever_hosting]
id: 8
</pre>

Removing the default group name <tt>default</tt> from the groups list is not recommended, and should only be done if you can ensure that each context of the installation has it's group assignment defined correctly in the property <tt>com.openexchange.context.group</tt>.

Having contexts separated into different groups also allows to use different global databases as defined in the additional sections of the configuration file <tt>globaldb.yml</tt>. Since context groups are bound to a configuration section by specifying the group name in the "groups" array, and each configuration section may target another global database, in theory there could be as much global databases as there are defined context groups. For example, to enforce data from the context groups <tt>smart_hosting</tt> and <tt>clever_hosting</tt> being stored at separate databases, the following configuration sections would route them to the database identifiers <tt>8</tt> and <tt>14</tt> respectively:

<pre>
clever:
groups: [clever_hosting]
id: 8

smart:
groups: [smart_hosting]
id: 14
</pre>

== Reload global db configuration ==

After updating the globaldb.yml you have to reload the server configuration by using /opt/open-xchange/sbin/reloadconfiguration command line tool.

[[Category: AppSuite]]
[[Category: Administrator]]
[[Category: Database]]

AppSuite:Open-Xchange Installation Guide for Debian 8.0

2018-08-21T13:26:35Z

Choeger: /* Requirements */

{{Version|7.8.4, 7.10.x}}

= OX App Suite on Debian GNU/Linux 8.0 =

{{QuickInstIntro|release=appsuite}}

= Requirements =

* Plain installed Debian GNU/Linux 8.0, no graphical tools required
* A supported Java Virtual Machine ([[AppSuite:OX_System_Requirements#Java|learn more]])
* A working internet connection
* vim is not installed by default on Debian. If you want to copy & paste the commands from this article into a shell window, you need to <code>apt-get install vim</code> first.

= Debian Jessie backports repository for OpenJDK 8 (only for AppSuite 7.10.0) =

OX App Suite v7.10.0 requires OpenJDK 8 while for previous OX App Suite versions Java version 7 was required. Unfortunately Debian Jessie does not contain Java version 8. Therefore we need to install it from the Debian Jessie backports repositories to be able to run OX App Suite v7.10.0 on Debian Jessie.

Add the repository for Debian Jessie backports.

$ cat <<EOF > /etc/apt/sources.list.d/backports.list
deb http://<your debian mirror>/debian jessie-backports main
EOF

Furthermore you need to allow the Debian package manager to install the OpenJDK 8 related packages from the Debian Jessie backports repository. Normally these packages have less priority and are not chosen as installation candidates. Raise the priority as shown below:

$ cat <<EOF > /etc/apt/preferences.d/ca-certificates-java.pref
Package: ca-certificates-java
Pin: release a=jessie-backports
Pin-Priority: 501
EOF

Now the package manager is able to choose OpenJDK 8 from the Debian Jessie backports.

= Database installation =

Please consult our [[OXLoadBalancingClustering_Database#Standalone_database_setup|database installation instructions]] for information on how to install a database on the local system.

Before proceeding, make sure the local machine has got a working MySQL service in one of the supported versions / flavors with the configuration / tunings applied as mentioned on our [[My.cnf|corresponding page]].

{{AddReposDebian|debname=jessie|debnameox=DebianJessie|release=appsuite}}

= Updating repositories and install packages =

It is highly recommended to import the Open-Xchange build key to your package systems trusted keyring in order to make sure only Open-Xchange packages with valid signing are installed on the system. Otherwise you'll encounter warnings about untrusted package sources. To import the Open-Xchange buildkey, please refer to this quick guide: [[Importing_OX_Buildkey#Importing_key_into_apt_based_systems|Importing OX Buildkey]].

Reload the package index. This will download the package descriptions available at the software repositories and will enable the Open-Xchange repository as a valid source for signed packages:

$ apt-get update

The following command starts the download and installation process of all required package for Open-Xchange deployment:

{{OXPackageInstallation|installer=apt-get|javavendor=sun|release=appsuite}}

{{OXConfiguration}}

{{oxinstaller|connector=http}}

After initializing the configuration, restart the Open-Xchange Administration service by executing:

$ systemctl restart open-xchange

{{OXRegister|globaldb=true}}

= Configure services =

{{ApacheOXModsDebian|connector=http|extramods=lbmethod_byrequests}}

{{Template:ApacheAppSuiteConf|connector=http|connectorConf=/etc/apache2/conf-available/proxy_http.conf|apacheconf=/etc/apache2/sites-enabled/000-default.conf|docroot=/var/www/html|loadmodule=|syncProxyName=eas_oxcluster}}

Enable the proxy configuration

$ a2enconf proxy_http.conf

After the configuration is done, restart the Apache webserver

$ systemctl restart apache2

== Upgrade from Debian 7 ==

If you updated from Debian 7 to Debian 8 the proxy_http.conf file is still located in the <tt>conf.d</tt> directory which is not read in Debian 8. So you have to move the file to <tt>conf-available</tt> and execute <tt>a2enconf proxy_http</tt> afterwards.

== Apache Setting for more concurrent Connections ==

By default apache2 is configured to support 150 concurrent connections. This forces all parallel requests beyond that limit to wait. Especially if, for example, active sync clients maintain a permanent connection for push events to arrive. The following article explains how that can be done

[[Tune_apache2_for_more_concurrent_connections|Apache Setting for more concurrent Connections]]

{{ContextUserAndLogs}}

[[Category: AppSuite]]

AppSuite:Open-Xchange Installation Guide for Debian 8.0

2018-08-16T07:59:01Z

Choeger:

{{Version|7.8.4, 7.10.x}}

= OX App Suite on Debian GNU/Linux 8.0 =

{{QuickInstIntro|release=appsuite}}

= Requirements =

* Plain installed Debian GNU/Linux 8.0, no graphical tools required
* A supported Java Virtual Machine ([http://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Server_Platforms learn more])
* A working internet connection
* vim is not installed by default on Debian. If you want to copy & paste the commands from this article into a shell window, you need to <code>apt-get install vim</code> first.

= Debian Jessie backports repository for OpenJDK 8 (only for AppSuite 7.10.0) =

OX App Suite v7.10.0 requires OpenJDK 8 while for previous OX App Suite versions Java version 7 was required. Unfortunately Debian Jessie does not contain Java version 8. Therefore we need to install it from the Debian Jessie backports repositories to be able to run OX App Suite v7.10.0 on Debian Jessie.

Add the repository for Debian Jessie backports.

$ cat <<EOF > /etc/apt/sources.list.d/backports.list
deb http://<your debian mirror>/debian jessie-backports main
EOF

Furthermore you need to allow the Debian package manager to install the OpenJDK 8 related packages from the Debian Jessie backports repository. Normally these packages have less priority and are not chosen as installation candidates. Raise the priority as shown below:

$ cat <<EOF > /etc/apt/preferences.d/ca-certificates-java.pref
Package: ca-certificates-java
Pin: release a=jessie-backports
Pin-Priority: 501
EOF

Now the package manager is able to choose OpenJDK 8 from the Debian Jessie backports.

= Database installation =

Please consult our [[OXLoadBalancingClustering_Database#Standalone_database_setup|database installation instructions]] for information on how to install a database on the local system.

Before proceeding, make sure the local machine has got a working MySQL service in one of the supported versions / flavors with the configuration / tunings applied as mentioned on our [[My.cnf|corresponding page]].

{{AddReposDebian|debname=jessie|debnameox=DebianJessie|release=appsuite}}

= Updating repositories and install packages =

It is highly recommended to import the Open-Xchange build key to your package systems trusted keyring in order to make sure only Open-Xchange packages with valid signing are installed on the system. Otherwise you'll encounter warnings about untrusted package sources. To import the Open-Xchange buildkey, please refer to this quick guide: [[Importing_OX_Buildkey#Importing_key_into_apt_based_systems|Importing OX Buildkey]].

Reload the package index. This will download the package descriptions available at the software repositories and will enable the Open-Xchange repository as a valid source for signed packages:

$ apt-get update

The following command starts the download and installation process of all required package for Open-Xchange deployment:

{{OXPackageInstallation|installer=apt-get|javavendor=sun|release=appsuite}}

{{OXConfiguration}}

{{oxinstaller|connector=http}}

After initializing the configuration, restart the Open-Xchange Administration service by executing:

$ systemctl restart open-xchange

{{OXRegister|globaldb=true}}

= Configure services =

{{ApacheOXModsDebian|connector=http|extramods=lbmethod_byrequests}}

{{Template:ApacheAppSuiteConf|connector=http|connectorConf=/etc/apache2/conf-available/proxy_http.conf|apacheconf=/etc/apache2/sites-enabled/000-default.conf|docroot=/var/www/html|loadmodule=|syncProxyName=eas_oxcluster}}

Enable the proxy configuration

$ a2enconf proxy_http.conf

After the configuration is done, restart the Apache webserver

$ systemctl restart apache2

== Upgrade from Debian 7 ==

If you updated from Debian 7 to Debian 8 the proxy_http.conf file is still located in the <tt>conf.d</tt> directory which is not read in Debian 8. So you have to move the file to <tt>conf-available</tt> and execute <tt>a2enconf proxy_http</tt> afterwards.

== Apache Setting for more concurrent Connections ==

By default apache2 is configured to support 150 concurrent connections. This forces all parallel requests beyond that limit to wait. Especially if, for example, active sync clients maintain a permanent connection for push events to arrive. The following article explains how that can be done

[[Tune_apache2_for_more_concurrent_connections|Apache Setting for more concurrent Connections]]

{{ContextUserAndLogs}}

[[Category: AppSuite]]

AppSuite:UpdatingOXPackages

2018-08-16T07:00:26Z

Choeger:

<div class="title">Updating OX App Suite packages</div>

''Synopsys'': This article describes how to update OX App Suite packages from one service pack to another.

== Warnings ==

Before we begin, here are several things that you should keep in mind:
* If you are '''updating a cluster, please do it one node after the other'''. Turn the node off, update, turn it on again, make sure it works in the cluster. Have a look here, too: [[Running_a_cluster#Upgrading_a_single_Node|Upgrading a single node]]
* If you don't have a cluster of OX nodes, then your complete installation needs to be taken down temporarily.
* Please '''update the backend before the frontend'''.
* Please '''do not restart Open-Xchange during the database update'''. A database update can happen after installing minor or major updates. As soon as the first user tries to log in to the system or if any provisioning action is done, this update starts.

=== Upgrading to 7.8.4 ===
* During the upgrade to 7.8.4 the existing ''JAVA_XTRAOPTS'' configuration property of the middleware stack in the file ''ox-scriptconf.sh'' will automatically be split up and migrated to a new categories approach. Please have a look at [[AppSuite:MiddlewareStartup#Evaluate_JVM_commandline_options|JVM commandline options]] and review the automatically upgraded configuration file.

=== Upgrading to 7.10.0 ===

* OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read [[AppSuite:7_10_Database_Migration]] carefully to familiarize with the details, implications and our proposed upgrade path.
* v7.10.0 also requires OpenJDK 8. To update or install v7.10.0 on Debian Jessie, follow [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_8.0#Debian_Jessie_backports_repository_for_OpenJDK_8_.28only_for_AppSuite_7.10.0.29|these instructions]].

== How to get updates? ==

OX App Suite updates can be accessed by customers with a valid license.

In addition, you need to configure the [[OXReportClient]].

= Updating OX App Suite Packages =

== Installing Updates ==

A new service pack usually introduces new packages and requires configuration changes. To get all required new packages and configuration changes, the following '''must''' be done when installing updates.

(Please, keep the [[#Warning|warning about backend updates before frontend updates]] in mind)

=== On Debian based distributions ===

==== Debian Jessie ====

Add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianJessie/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianJessie /

Then run

$ apt-get update
$ apt-get dist-upgrade

Important: In case you are asked in the process if you would like to replace a configuration with the default delivered in the updated package please DO NOT replace but KEEP your existing configuration. In case something needs to be changed mandatorily this will be handled and modified by scripts which run after package installation automatically.

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>

==== Debian Stretch (valid from v7.10) ====

Add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianStretch/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianStretch /

Then run

$ apt-get update
$ apt-get dist-upgrade

Important: In case you are asked in the process if you would like to replace a configuration with the default delivered in the updated package please DO NOT replace but KEEP your existing configuration. In case something needs to be changed mandatorily this will be handled and modified by scripts which run after package installation automatically.

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>

=== On RPM based distributions ===

==== RHEL6/CentOS6 ====

Add the following entries to <tt>/etc/yum.repos.d/ox.repo</tt>:

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== RHEL7/CentOS7 ====

Add the following entries to <tt>/etc/yum.repos.d/ox.repo</tt>:

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== SLES12 ====

Add the updates repository to the repository list:

$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/SLE_12/ OXAPPSUITEUIUPDATES
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12/ OXBACKENDUPDATES

and run

$ zypper dup -r OXAPPSUITEUIUPDATES
$ zypper dup -r OXBACKENDUPDATES

You might need to run

$ zypper ref

to update the repository metadata before running ''zypper up''.

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ rcopen-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind.

= Updating OX App Suite Packages for older versions =

== Installing Updates ==

A new service pack usually introduces new packages and requires configuration changes. To get all required new packages and configuration changes, the following '''must''' be done when installing updates.

(Please, keep the [[#Warning|warning about frontend updates before backend updates]] in mind)

=== On Debian based distributions ===

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>. Replace VERSION with the version you are using (e.g. 7.6.2). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianWheezy/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianWheezy/ /

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianJessie/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianJessie /

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianStretch/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianStretch /

Then run

$ apt-get update
$ apt-get dist-upgrade

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>

=== On RPM based distributions ===

==== RHEL6/CentOS6 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/yum.repos.d/ox.repo</tt>. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== RHEL7/CentOS7 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/yum.repos.d/ox.repo</tt>. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== SLES 11 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to the repository list. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/SLES11/ OXAPPSUITEUIUPDATES
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/SLES11/ OXBACKENDUPDATES

and run

$ zypper dup -r OXAPPSUITEUIUPDATES
$ zypper dup -r OXBACKENDUPDATES

You might need to run

$ zypper ref

to update the repository metadata before running ''zypper up''.

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ rcopen-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind.

==== SLES 12 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to the repository list. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/SLE_12/ OXAPPSUITEUIUPDATES
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/SLE_12/ OXBACKENDUPDATES

and run

$ zypper dup -r OXAPPSUITEUIUPDATES
$ zypper dup -r OXBACKENDUPDATES

You might need to run

$ zypper ref

to update the repository metadata before running ''zypper up''.

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ rcopen-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind.

= Updating UI plugins =

If you update only UI plugins without simultaneously upgrading the core UI packages to a new version, you need to perform an additional step after the update to make the changes visible to users.

The package <tt>open-xchange-appsuite</tt> contains a timestamp which is different in each version. The JavaScript UI in every user's browser will reload all cached code and data whenever this value changes. Since this value does not change when updating only plugin packages, the value must be changed manually with the following command:

$ /opt/open-xchange/sbin/touch-appsuite --timestamp=20170101.123400

If you only have one OX node, the parameter <code>--timestamp</code> can be omitted. It defaults to the current UTC time anyway.

When updating a cluster, the command must use the same timestamp value on every node. Otherwise, browsers will clear their cache and re-download the entire UI code every time load balancer sends them to a different node (i.e. on almost every login). This is also why the timestamps can't be updated automatically: a node doesn't know which value other nodes will pick, which of them are part of the same update, etc.

The quickest way to obtain a value for the timestamp parameter is to run the command with the parameter <code>-h</code>. It will then print a help message with the current time as an example. For automation, you can use the output of

date -u +%Y%m%d.%H%M%S

Again: this value must be computed once, and then the same value must be used on every node in the cluster.

This step can be performed on each node separately after each node has been updated, or on all nodes at once after all nodes have been updated. If Apache has its own set of dedicated nodes, the <tt>touch-appsuite</tt> call must be performed on the web server nodes, after all corresponding <tt><plugin>-static</tt> packages have been updated.

[[Category: OX7]]
[[Category: AppSuite]]

[[Category: Administrator]]

AppSuite:UpdatingOXPackages

2018-08-16T06:47:15Z

Choeger:

<div class="title">Updating OX App Suite packages</div>

''Synopsys'': This article describes how to update OX App Suite packages from one service pack to another.

== Warnings ==

Before we begin, here are several things that you should keep in mind:
* If you are '''updating a cluster, please do it one node after the other'''. Turn the node off, update, turn it on again, make sure it works in the cluster. Have a look here, too: [[Running_a_cluster#Upgrading_a_single_Node|Upgrading a single node]]
* If you don't have a cluster of OX nodes, then your complete installation needs to be taken down temporarily.
* Please '''update the backend before the frontend'''.
* Please '''do not restart Open-Xchange during the database update'''. A database update can happen after installing minor or major updates. As soon as the first user tries to log in to the system or if any provisioning action is done, this update starts.

=== Upgrading to 7.8.4 ===
* During the upgrade to 7.8.4 the existing ''JAVA_XTRAOPTS'' configuration property of the middleware stack in the file ''ox-scriptconf.sh'' will automatically be split up and migrated to a new categories approach. Please have a look at [[AppSuite:MiddlewareStartup#Evaluate_JVM_commandline_options|JVM commandline options]] and review the automatically upgraded configuration file.

=== Upgrading to 7.10.0 ===

* OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read http://oxpedia.org/wiki/index.php?title=AppSuite:7_10_Database_Migration carefully to familiarize with the details, implications and our proposed upgrade path.
* v7.10.0 also requires OpenJDK 8. To update or install v7.10.0 on Debian Jessie, follow [[AppSuite:Open-Xchange_Installation_Guide_for_Debian_8.0#Debian_Jessie_backports_repository_for_OpenJDK_8_.28only_for_AppSuite_7.10.0.29|these instructions]].

== How to get updates? ==

OX App Suite updates can be accessed by customers with a valid license.

In addition, you need to configure the [[OXReportClient]].

= Updating OX App Suite Packages =

== Installing Updates ==

A new service pack usually introduces new packages and requires configuration changes. To get all required new packages and configuration changes, the following '''must''' be done when installing updates.

(Please, keep the [[#Warning|warning about backend updates before frontend updates]] in mind)

=== On Debian based distributions ===

==== Debian Jessie ====

Add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianJessie/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianJessie /

Then run

$ apt-get update
$ apt-get dist-upgrade

Important: In case you are asked in the process if you would like to replace a configuration with the default delivered in the updated package please DO NOT replace but KEEP your existing configuration. In case something needs to be changed mandatorily this will be handled and modified by scripts which run after package installation automatically.

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>

==== Debian Stretch (valid from v7.10) ====

Add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianStretch/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianStretch /

Then run

$ apt-get update
$ apt-get dist-upgrade

Important: In case you are asked in the process if you would like to replace a configuration with the default delivered in the updated package please DO NOT replace but KEEP your existing configuration. In case something needs to be changed mandatorily this will be handled and modified by scripts which run after package installation automatically.

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>

=== On RPM based distributions ===

==== RHEL6/CentOS6 ====

Add the following entries to <tt>/etc/yum.repos.d/ox.repo</tt>:

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== RHEL7/CentOS7 ====

Add the following entries to <tt>/etc/yum.repos.d/ox.repo</tt>:

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== SLES12 ====

Add the updates repository to the repository list:

$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/SLE_12/ OXAPPSUITEUIUPDATES
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/SLE_12/ OXBACKENDUPDATES

and run

$ zypper dup -r OXAPPSUITEUIUPDATES
$ zypper dup -r OXBACKENDUPDATES

You might need to run

$ zypper ref

to update the repository metadata before running ''zypper up''.

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ rcopen-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind.

= Updating OX App Suite Packages for older versions =

== Installing Updates ==

A new service pack usually introduces new packages and requires configuration changes. To get all required new packages and configuration changes, the following '''must''' be done when installing updates.

(Please, keep the [[#Warning|warning about frontend updates before backend updates]] in mind)

=== On Debian based distributions ===

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/apt/sources.list.d/open-xchange.list</tt>. Replace VERSION with the version you are using (e.g. 7.6.2). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianWheezy/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianWheezy/ /

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianJessie/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianJessie /

deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/DebianStretch/ /
deb http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/DebianStretch /

Then run

$ apt-get update
$ apt-get dist-upgrade

If you want to see, what apt-get is going to do without actually doing it, you can run:

$ apt-get dist-upgrade -s

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>

=== On RPM based distributions ===

==== RHEL6/CentOS6 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/yum.repos.d/ox.repo</tt>. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/RHEL6/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== RHEL7/CentOS7 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to <tt>/etc/yum.repos.d/ox.repo</tt>. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

[ox-updates-appsuiteui]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

[ox-updates-backend]
name=Open-Xchange Updates
baseurl=http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/RHEL7/
gpgkey=http://software.open-xchange.com/oxbuildkey.pub
enabled=1
gpgcheck=1
metadata_expire=0m

and run

$ yum update

$ yum upgrade

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ /etc/init.d/open-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind)

==== SLES 11 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to the repository list. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/SLES11/ OXAPPSUITEUIUPDATES
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/SLES11/ OXBACKENDUPDATES

and run

$ zypper dup -r OXAPPSUITEUIUPDATES
$ zypper dup -r OXBACKENDUPDATES

You might need to run

$ zypper ref

to update the repository metadata before running ''zypper up''.

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ rcopen-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind.

==== SLES 12 ====

If you want to update an older version of Open-Xchange App Suite to the latest maintenance release, add the following entry to the repository list. Replace VERSION with the version you are using (e.g. 7.4.2, 7.6.0). See [[AppSuite:Version_Support_Committment]] for the currently supported versions. Also, make sure that your repository configuration points at the versioned base installation repositories (instead of using the <tt>stable</tt> symlink.)

$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/appsuiteui/updates/SLE_12/ OXAPPSUITEUIUPDATES
$ zypper ar http://CUSTOMERID:PASSWORD@software.open-xchange.com/products/appsuite/VERSION/backend/updates/SLE_12/ OXBACKENDUPDATES

and run

$ zypper dup -r OXAPPSUITEUIUPDATES
$ zypper dup -r OXBACKENDUPDATES

You might need to run

$ zypper ref

to update the repository metadata before running ''zypper up''.

After the new packages are installed, the open-xchange process needs a restart:

<pre>$ rcopen-xchange restart</pre>
(Please, keep the [[#Warnings|warning about database updates]] in mind.

= Updating UI plugins =

If you update only UI plugins without simultaneously upgrading the core UI packages to a new version, you need to perform an additional step after the update to make the changes visible to users.

The package <tt>open-xchange-appsuite</tt> contains a timestamp which is different in each version. The JavaScript UI in every user's browser will reload all cached code and data whenever this value changes. Since this value does not change when updating only plugin packages, the value must be changed manually with the following command:

$ /opt/open-xchange/sbin/touch-appsuite --timestamp=20170101.123400

If you only have one OX node, the parameter <code>--timestamp</code> can be omitted. It defaults to the current UTC time anyway.

When updating a cluster, the command must use the same timestamp value on every node. Otherwise, browsers will clear their cache and re-download the entire UI code every time load balancer sends them to a different node (i.e. on almost every login). This is also why the timestamps can't be updated automatically: a node doesn't know which value other nodes will pick, which of them are part of the same update, etc.

The quickest way to obtain a value for the timestamp parameter is to run the command with the parameter <code>-h</code>. It will then print a help message with the current time as an example. For automation, you can use the output of

date -u +%Y%m%d.%H%M%S

Again: this value must be computed once, and then the same value must be used on every node in the cluster.

This step can be performed on each node separately after each node has been updated, or on all nodes at once after all nodes have been updated. If Apache has its own set of dedicated nodes, the <tt>touch-appsuite</tt> call must be performed on the web server nodes, after all corresponding <tt><plugin>-static</tt> packages have been updated.

[[Category: OX7]]
[[Category: AppSuite]]

[[Category: Administrator]]

Contact-Support

2018-08-01T04:48:55Z

Choeger:

= How to contact the Open-Xchange Support? =

= Concern: =
You are entitled for Advanced Support and have obtained one of Open-Xchange's Support offerings, have registered all your Support Keys, which you have got after purchasing your Support offering according the information provided in the [http://knowledgebase.open-xchange.com/support/self-service/registration.html My Registrations] section.

Furthermore you have an issue with your Open-Xchange Software and need help by the Open-Xchange Support.

= Todo: =
Send an E-Mail to <support AT open-xchange.com> and provide the following information within the E-Mail body. Please take care to put your Support Key always to the top. If you provide more than one key the first recognised key wins.

IMPORTANT: We can only guarantee fast responses in case you report your incident or problem in English.

Support Key: OX-SUPPORT-OR-LICENSE-KEY-XXX
Server: url of the machine
Server Version: server version or package list
Platform: Please choose one from [https://oxpedia.org/wiki/index.php?title=Contact-Support:PossibleValues#Platform: possible values].
GUI Version: GUI version or package list
Category: Please choose one from [https://oxpedia.org/wiki/index.php?title=Contact-Support:PossibleValues#Category: possible values].
Severity: 4, 3, 2, 1 (see description of Severity Levels)
Track-ID: the customer's internal tracking number, e.g. from its Bugzilla
Product: Please choose one from [https://oxpedia.org/wiki/index.php?title=Contact-Support:PossibleValues#Product: possible values].

Steps to reproduce:
...

Current behaviour:
...

Expected behaviour:
...

The Severity of an Incident determines the impact it has on the customer's business and therefore the urgency of solving an Incident of certain impact.

'''Important:''' Please note that Open-Xchange's response time depends on both the Severity and the Service Level Agreement between the customer and Open-Xchange.

If all of the above information has been provided a confirmation mail is sent from Open-Xchange's ticket system which includes the ticket number for that incident.

= Open-Xchange Severity: =

== Severity 1==

Shall mean Incidents that are defined as a complete outage and do not allow the Licensee to further conduct his business. Licensee's system or application is completely not available and no Workaround exists. The Incident affects all users deployed on the Joint Solution Environment.
Also means a security or general threat causing potential risk to the customers’ data integrity or privacy.
A situation in which one or several servers do not operate correctly is not a Severity 1 issue, unless the issue causes one of the above to happen.

==Severity 2==

The Licensee’s operation is severely disrupted. A business critical component of the Joint Solution Environment cannot be used by a majority of the users.

==Severity 3==

Shall mean Incidents which involve partial loss of non-critical functionality, one which impairs many operations, but allows the Licensee to continue to operate.

==Severity 4==

Shall mean general usage questions, recommendations for product enhancements or modifications, and calls that are passed to the Parties for informational purposes. This includes but is not limited to documentation and translation errors.

= Personal Data Policy =
According to German law, companies are forced to handle any (log) files from customers which contain data related to a third person or has any personal protection in a special way. Personal data shall mean any information concerning the personal or material circumstances of an identified or identifiable natural person. Even so they have to be deleted once they aren't used any more. To fulfil this requirement, customers and support agents have to keep the readable ticket communication, in form of email/article body, subject or attachment names, free from any personal data. This can be every thing from names, email addresses, screen-shots, logs files and even credentials to system accounts. This personal data only has to be handed over in form of attachments which was common practice before. Transfer channels for personal data are attachments via the ticket system, attachment in encrypted emails or provided by protected download links. How to send encrypted emails via PGP is described [http://sdb.open-xchange.com/node/59 here].

The integrity of an 'Incident Request' with all available data needs to be saved up to 90 days after a ticket was closed to ensure a holistic assessment in case of Contractual complaints. This time frame is mandatory and gives also the customer time for detailed tests. In case of reopening an incident within these three months all information is still available and needs not to be recollected by customers and end users.

Open-Xchange introduced a weekly deletion process, the deletion work on ticket attachments and on raw email files which are affected by attachments. The automatic deletion of all ticket attachments takes place weekly at Sunday and affects all tickets which are in a 'closed' state since 90 days.

= Creating an OX Support Tarball =

[http://oxpedia.org/wiki/index.php?title=AppSuite:Oxsysreport Creating an OX Support Tarball]

Kontakt-Zu-Support

2018-08-01T04:48:48Z

Choeger:

= Open-Xchange Support kontaktieren =

= Anliegen: =
Sie sind im Besitz eines erweiterten Support Vertrags mit Open-Xchange, Sie haben Ihren Support Key, wie unter [http://knowledgebase.open-xchange.com/support/self-service/registration.html Meine Registrierungen] beschrieben freigeschaltet und benötigen nun Unterstützung bei der Lösung eines Problems mit Ihrem Open-Xchange Produkt.

= Vorgehen: =
Senden Sie eine E-Mail an <support AT open-xchange.com> und fügen Sie folgende Informationen dem "Mail Body" bei. Bitte achten Sie darauf, den Support Key immer an oberster Stelle anzugeben. Sollten mehrere Keys in der Mail erkannt werden, so gewinnt der zuerst erkannte:

WICHTIG: Wir können schnelle Antworten nur garantieren, wenn Sie ihre Störungen und Probleme in englisch melden.

Support Key: OX-SUPPORT-ODER-LIZENZ-KEY-XXX
Server: URL des Servers
Server Version: Server Version oder Paket Liste
Platform: Bitte wählen Sie einen Eintrag aus den [https://oxpedia.org/wiki/index.php?title=Contact-Support:PossibleValues#Platform: möglichen Werten].
GUI Version: GUI Version oder Paket Liste
Category: Bitte wählen Sie einen Eintrag aus den [https://oxpedia.org/wiki/index.php?title=Contact-Support:PossibleValues#Module: möglichen Werten].
Severity: 4, 3, 2, 1 (siehe auch Beschreibung der Severity Level)
Track-ID: Kunden interne Nachverfolgungsreferenz, z.B. dessen Bugzilla
Product: Bitte wählen Sie einen Eintrag aus den [https://oxpedia.org/wiki/index.php?title=Contact-Support:PossibleValues#Product: möglichen Werten].

Steps to reproduce:
...
Current behaviour:
...
Expected behaviour:
...

Die Severity (Schwere) einer Anfrage beschreibt den Einfluss einer Störung auf den Geschäftsablauf eines Kunden und somit die Dringlichkeit der Beseitigung einer möglichen Störung.

'''Wichtig:''' Die Reaktionszeit von Open-Xchange hängt sowohl von der gewählten Severity der Anfrage als auch von einem "Service Level Agreement" (SLA) zwischen dem Kunden und Open-Xchange ab.

Sobald alle obigen Informationen in der Anfrage enthalten sind, wird eine Bestätigungs E-Mail von dem Open-Xchange Ticketsystem verschickt, welche die Ticketnummer für die weitere Kommunikation enthält.

= Open-Xchange Severity (English only) =

== Severity 1==

Shall mean Incidents that are defined as a complete outage and do not allow the Licensee to further conduct his business. Licensee's system or application is completely not available and no Workaround exists. The Incident affects all users deployed on the Joint Solution Environment.
Also means a security or general threat causing potential risk to the customers’ data integrity or privacy.
A situation in which one or several servers do not operate correctly is not a Severity 1 issue, unless the issue causes one of the above to happen.

==Severity 2==

The Licensee’s operation is severely disrupted. A business critical component of the Joint Solution Environment cannot be used by a majority of the users.

==Severity 3==

Shall mean Incidents which involve partial loss of non-critical functionality, one which impairs many operations, but allows the Licensee to continue to operate.

==Severity 4==

Shall mean general usage questions, recommendations for product enhancements or modifications, and calls that are passed to the Parties for informational purposes. This includes but is not limited to documentation and translation errors.

= Personal Data Policy (English only) =
According to German law, companies are forced to handle any (log) files from customers which contain data related to a third person or has any personal protection in a special way. Personal data shall mean any information concerning the personal or material circumstances of an identified or identifiable natural person. Even so they have to be deleted once they aren't used any more. To fulfil this requirement, customers and support agents have to keep the readable ticket communication, in form of email/article body, subject or attachment names, free from any personal data. This can be every thing from names, email addresses, screen-shots, logs files and even credentials to system accounts. This personal data only has to be handed over in form of attachments which was common practice before. Transfer channels for personal data are attachments via the ticket system, attachment in encrypted emails or provided by protected download links. How to send encrypted emails via PGP is described [http://sdb.open-xchange.com/node/59 here].

The integrity of an 'Incident Request' with all available data needs to be saved up to 90 days after a ticket was closed to ensure a holistic assessment in case of Contractual complaints. This time frame is mandatory and gives also the customer time for detailed tests. In case of reopening an incident within these three months all information is still available and needs not to be recollected by customers and end users.

Open-Xchange introduced a weekly deletion process, the deletion work on ticket attachments and on raw email files which are affected by attachments. The automatic deletion of all ticket attachments takes place weekly at Sunday and affects all tickets which are in a 'closed' state since 90 days.

= Erstellung eines OX Support Tarball =

[http://oxpedia.org/wiki/index.php?title=AppSuite:Oxsysreport Erstellung eines OX Support Tarball]

AppSuite:OX System Requirements

2018-07-18T11:26:34Z

Choeger: /* Object Storages */

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility. This overview makes no claim to be complete.

Open-Xchange Server 6 overview tables about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility are available at [[OX_System_Requirements|OX 6 Requirements - Open-Xchange supported components overview]]

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Hardware Requirements ==
=== General Assumptions ===
Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.

This means in particular, but not only:

* Infrastructure is "quasi-static". We don't need to take into account things like VMs coming and going dynamically, dynamic IPs, volatile ("ephemeral") data
* "Database as a service" is not allowed. This typically is a highly customized "MySQL like" storage engine, and not a true MySQL, and we can't control flavor, version, setup, etc. If need for configuration changes is identified, we won't be able to change anything.

So to summarize: we expect any virtualized platform to behave and work just like a well-known non-virtualized / physical platform.

Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.

Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.

'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''

=== High Level Design / OS setup ===
Operate services separately (USM, Document/Image Converters) as described in Cluster Setup.

Clocks between all nodes must be synchronized (e.g. via NTP).

Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.

Platform Architecture: 64 bit versions (x84_64) of the supported [[#Software Requirements | Linux distributions]]

=== Node Sizing ===
* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)
* 4 CPU cores (virtual, physical or hyperthreads)
* Disk space
** 5 GB for OS and software
** <code>2 * system memory</code> of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps

=== Untested/Unsupported Deployments ===
* Changes to Garbage Collector settings
* Running in containerized environments (Docker, rkt)
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration
* Cloud platform services (PaaS) like database systems (for example AWS RDS)
* Multi-site active-active

== Software Requirements ==

=== Linux Distributions ===

OX App Suite is available as Linux packages for the following distributions:

{|border="2" rules="all" align="left">
|'''Distribution'''
|'''Versions'''
|'''Derivates'''
|-
| 
| 
| 
|-
|Suse Linux Enterprise Server
|12
|None
|-
|Red Hat Enterprise Linux
|6,7
|CentOS
|-
|Debian
|8 (Jessie), 9 (stretch)
|None
|-
|}

=== Java ===

OX App Suite Middleware requires OpenJDK headless JRE 8 or 9.

'''Please note:''' For Debian 8 (Jessie) OpenJDK 8 is only available via the [https://packages.debian.org/search?keywords=jessie-backports jessie-backports] repository.

=== Databases ===

OX App Suite uses MySQL with the InnoDB storage engine as its primary data store. The following vendors and products are supported.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''Versions'''
|-
| 
| 
| 
|-
|Oracle
|MySQL Community Edition, Standard Edition, Enterprise Edition
|[5.6.x, 5.7.x]
|-
|MariaDB
|MariaDB Server, Galera Cluster
|[10.1.x, 10.2.x]
|-
|Percona
|XtraDB Cluster
|[5.6.x, 5.7.x]
|-
|}

=== Important Notes ===

* For some Linux distributions the included MySQL/MariaDB packages are too old to be used with App Suite. It is mandatory then to install a supported version from upstream package sources. Possible sources are the official vendor repositories of MySQL, MariaDB or Percona as well as for example Red Hat Software Collections.
* Required MySQL configuration differs between App Suite 7.8.4 and 7.10.0 and also between the different database systems in terms of SQL modes. See [[My.cnf]] for details.
* For upgrades to App Suite 7.10.0 a comprehensive database upgrade guide exists: [[AppSuite:7_10_Database_Migration]]

== File Storage ==

=== Temporary Data ===

OX App Suite stores temporary files in the local file system, e.g. for spooling of uploaded data. Any file system supported by the installed JRE is suitable.

=== Persistent Data ===

Persistent data like OX Drive files, PIM attachments etc. needs to be stored in a distributed file system that is available from all server nodes. For single-node setups a local file system mount point can be used, small to mid-scale setups can be powered by NFS. For large-scale setups object storages should be considered.

==== Object Storages ====

OX App Suite ships with different optional adapters to support object storages.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''API'''
|'''Remarks'''
|-
| 
| 
| 
| 
|-
|Amazon
|AWS S3
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|CEPH
|RadosGW
|S3 HTTP API
|See also [[AppSuite:S3_File_Store]]
|-
|Scality
|Scality RING
|Sproxyd HTTP API
|See also [[AppSuite:Scality_File_Store]]
|-
|OpenStack
|Swift
|Object Storage API V1
|Support for Swift is experimental and could be removed again in the future. See also [[AppSuite:Swift_File_Store]]
|-
|}

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Microsoft Internet Explorer 10/11
|v7.6.3
|-
|Microsoft Internet Explorer 11/Edge
|v7.8.4, v7.10.0
|-
|Mozilla Firefox (latest & previous version)
|v7.8.4, v7.10.0
|-
|Google Chrome (latest & previous version)
|v7.8.4, v7.10.0
|-
|Apple Safari (10.01 & 10.03; Mac OS X only)
|v7.8.4, v7.10.0
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 10 / iOS 11
|Safari
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 10 / iOS 11
|Safari
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|}

== Calendar/Contact synchronization Apple Mac OS X ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Mac OS X 10.11 (El Capitan)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|macOS 10.12, 10.13 (Sierra & High Sierra)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 10 / iOS 11
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|-
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|-
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|-
| 
| 
|-
|Windows Phone 8 (latest & previous minor versions), Windows Phone 10 (latest & previous minor versions)
|[[File:check.gif]]
|-
|Apple iOS 10 / iOS 11
|[[File:check.gif]]
|-
|Android 4.1 or later
|[[File:check.gif]]
|-
|}

== OX Drive for Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|OX Drive for Windows
|Latest versions of Windows 8, latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|-
|OX Drive for Mac OS
|Mac OS X 10.11 (El Capitan), macOS 10.12, 10.13 (Sierra & High Sierra)
|-
|OX Drive for iOS
|Apple iOS 10, Apple iOS 11
|-
|OX Drive for Android
|Smartphone on Android 4.1 or later with Chrome (latest & previous version), Tablets on Android 4.1 or later with Chrome (latest & previous version)
|-
|}

== OX Mail App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|OX Mail for iOS
|Apple iOS 10, Apple iOS 11
|-
|OX Mail for Android
|Smartphone on Android 4.3 or later
|-
|}

== OX Mail App v2 ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Main_Page_Quickinstall#Quick_Installation_Guide OX App Suite]
|OX App Suite v7.8.4 or later
|-
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Mobile_API_Facade Mobile API Facade]
|Mobile API Facade v1.0.2 or later (until OX App Suite v7.8.4) Mobile API Facade v1.2.0 or later (from OX App Suite v7.10.0)
|-
|Push Notification Package
|Package "open-xchange-mobile-api-facade-push-certificates" (available to App Suite licensees only)
|-
|OX Mail App v2.0 for iOS
|Apple iOS 9.3, iOS 10, iOS 11 Server reachable via TLS 1.2
|-
|OX Mail App v2.0 for Android
|Android 5.0 (Lollipop) or higher Server reachable via TLS 1.2
|-
|}

== OX Sync App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|OX Sync App for Android
|Smartphone on Android 4.0 or later
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX Guard since v2.6.0: OX App Suite v7.8.3 OX Guard since v2.8.0: OX App Suite v7.8.4 OX Guard since v2.10.0: OX App Suite v7.10.0
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 10 / iOS 11: Safari (latest version & previous version) Smartphone on Android 4.1 or later: Chrome (latest & previous version) Apple iPad (all devices) on iOS 10 / iOS 11: Safari Safari (latest version & previous version) Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|}

== eM Client for OX App Suite ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|[http://oxpedia.org/wiki/index.php?title=AppSuite:EM_Client_for_OX_App_Suite '''eM Client for OX App Suite''']
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|Client PC operating system
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|-
|}

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:7 10 Database Migration

2018-07-18T11:14:24Z

Choeger: /* Database System */

{{Version|7.10.0}}

= Database Migration with OX App Suite v7.10.0 =

OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read this paper carefully to ensure a smooth and clean upgrade process.

== Change Overview ==

The most significant changes are:
* New version and configuration requirements.
* Most VARCHAR columns need to be migrated to utf8mb4 character encoding.
* A major rewrite of the calendar application requires full data migration.

We strongly recommend to thoroughly plan and test the upgrade procedure. To gain insights about update task runtimes and the expected load, our recommendation is to clone ConfigDB and the biggest UserDB and perform an isolated test upgrade that especially covers the calendar migration and character encoding changes. Update task durations can be significantly longer than with previous upgrades and the migrations might cause noticeable higher I/O load. Also some additional disk space is needed during and after the migrations.

== Database System ==

MySQL Server is supported in versions 5.6 and 5.7 with recent patch levels only and MariaDB Server 10.1 and 10.2 respectively. Support for 5.6/10.1 exists for compatibility reasons and is transitional. We recommend upgrading to 5.7/10.2 as soon as possible. Any database system upgrade must happen before App Suite is upgraded to OX App Suite v7.10.0. Please follow the respective guides of your database vendor carefully.

Different App Suite and database system versions require different configurations of the DBMS, please follow [[My.cnf]] to have your database configured in a sane way. Especially the following items require some attention with the upgrade to App Suite 7.10.0 and upgrades of the DBMS itself:

* Supported SQL modes are only <code>NO_ENGINE_SUBSTITUTION</code> and <code>NO_AUTO_CREATE_USER</code>. Starting with App Suite 7.10.0, <code>ONLY_FULL_GROUP_BY</code> is also supported for MySQL 5.7. It is still not with older versions of MySQL or any MariaDB version! To review the current value, use <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'sql_mode';</code>.
* Ensure that <code>character_set_server</code> is set to <code>utf8</code> for App Suite 7.8.x. Again the current global default value can be obtained via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'character_set_server';</code>. With 7.10.0 being fully rolled out, this setting must then be changed to <code>utf8mb4</code>. If <code>collation_server</code> is configured explicitly, it must be set to a matching value according to the character set in either case!

Note that App Suite <= 7.8.4 did not support MySQL 5.7/MariaDB 10.2 so far. While we recommend it for 7.10.0, this leaves a lack of definition during the upgrade process. We consider running 7.8.4 on top of MySQL 5.7/MariaDB 10.2 a valid scenario as long as it is transitional during the upgrade phase. Please take our configuration recommendations seriously to mitigate potential user-facing issues as far as possible.

== Upgrade Procedure ==

The upgrade to OX App Suite v7.10.0 can be performed like any other major upgrade before. However, the duration of blocking database update tasks for the mentioned charset and calendar migrations could conflict with customers’ availability demands. Therefore it is possible to decouple these special time- and resource-intensive tasks from the plain version upgrade. In this section a multi-step approach is described that performs the version upgrade before and independently from the migrations. Every step always results in a working system that is ready to serve user traffic. Some functional implications that affect user experience are outlined in the according subsections.

'''Important:''' Even though the first step leads to a basically working OX App Suite v7.10.0 environment, the subsequent steps are not optional but mandatory! Skipping the migrations will leave a few calendar features dysfunctional and can lead to issues with certain SQL queries that use explicit collations for searching and sorting. Running OX App Suite v7.10.0 in production without having all parts of the migration fulfilled is not supported – OX support will request you to complete the migration tasks when reporting issues that are not related to the migration itself.

== Initial OX App Suite v7.10.0 Rollout ==
If not done so far, upgrade your MySQL installation to a version supported with OX App Suite v7.10.0 but configure it to be compatible with OX App Suite v7.8.x as described in the “Database System” section.

Despite the fact that the two special migrations for calendar and character sets are explicitly skipped, this section assumes that the “Rolling Upgrade with breaking Hazelcast upgrade” is applied as described in [[AppSuite:Running_a_cluster#Updating_a_Cluster]]. For the application server upgrade, the common guide from [[AppSuite:UpdatingOXPackages]] can be followed.

Prepare a dedicated App Suite middleware node that will be used to perform the database update tasks. The node must not be serving any user traffic and be prepared with

* OX App Suite v7.10.0 packages
* Configuration according to the user production nodes
* The Hazelcast rolling upgrade compatibility package (see [[AppSuite:Running_a_cluster#Rolling_Upgrade_with_breaking_Hazelcast_upgrade]])
* Exclude the update tasks for both mentioned migrations (i.e. calendar and character encoding). See “Update Task Exclusion” for details.
* Execute update tasks according to your preferred strategy. More on this can be found at [[UpdateTasks]].

By default (if using the "runallupdate" tool") update tasks operate on database schemas sequentially, one at a time. All users from all contexts of a given schema are logged out and locked out. Then, DB schema changes are executed. Finally, users are unlocked and able to login again. Schemas typically contain a few thousand users (if our recommended sizing is being followed) and thus executing update tasks means bunches of a few thousand users will be affected sequentially. You will not have a full downtime. For each update task execution process the following statements hold true:

* All users got service for nearly all the time (all the time but the time where their schema is upgraded)
* For each point in time, nearly all users got service (all but the ones from the currently updated schema)
* When update tasks are completed, all users will have been affected by one "logout" - "locked out" cycle

After complete and successful update task execution, roll out OX App Suite v7.10.0 to one node after another. After complete rollout, reconfigure MySQL if appropriate as described in the “Database System” section.

=== Update Task Exclusion ===

Add the following lines to <code>/opt/open-xchange/etc/excludedupdatetasks.properties</code> or remove the leading # character if already included, so that it contains these two lines:

# Character Encoding Migration
com.openexchange.groupware.update.excludedUpdateTasks=groupware.utf8mb4

# Calendar Migration
com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask

The first line does not denote one dedicated update task, but a whole list of tasks. To make exclusion more convenient, the concept of update task namespaces has been introduced. All update tasks belonging to the character encoding migration are part of the <code>groupware.utf8mb4</code> namespace. The denoted property takes care of excluding them all at once. You can list all according tasks with the <code>/opt/open-xchange/sbin/listUpdateTaskNamespaces</code> tool.

== Character Encoding Migration ==

The default character encoding for Unicode (named character set by MySQL) of MySQL will become <code>utf8mb4</code> in the near future. MariaDB on Debian Stretch (9) already has an according default configuration set when installing it from distribution packages. So far all VARCHAR columns are supposed to store at max. 3-byte UTF-8 characters due to the nature of MySQL’s utf8 character encoding. This leads to the fact that for example emojis cannot be saved as part of any App Suite entities. In a mixed-mode scenario (App Suite considers MySQL to operate in utf8mb4 mode due to the <code>character_set_server</code> setting, while columns are specified with utf8 encoding), this leads to issues whenever certain collations during SELECT statements are enforced. To avoid such issues generally and also increase user experience by finally allowing characters from the Unicode astral plane, Open-Xchange has decided to migrate existing data structures to the utf8mb4 character encoding.

This migration can be executed before or after the calendar migration, while it is recommend to execute it before.

The upgrade procedure is basically the same as above in terms executing update tasks, while the server software is already up to date and needs no further upgrades:

* Again prepare one dedicated node that doesn’t serve any user traffic
* Remove the according namespace property from <code>excludedupdatetasks.properties</code> again, but still keep the “ChronosStorageMigrationTask”. Afterwards restart the open-xchange daemon.
* Execute update tasks according to your preferred strategy.

'''Important:''' The update tasks require a lot of tables to be copied and re-created, leading to high I/O and especially sequential read and write operations. For every copied table the needed MySQL disk space doubles during the update task, so ensure enough free space before running the migration.

== Calendar Data Migration ==

The new calendar stack in OX App Suite v7.10.0 comes along with a new data model using its very own tables in MySQL. To preserve users calendar data, an update task <code>com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask</code> has been introduced, that reads all data from the old tables, applies transformations to match the new stack and writes it into the new tables. The approach and upgrade process is described in detail at https://documentation.open-xchange.com/7.10.0/middleware/components/calendar/data_migration.html. Please read that article carefully before continuing. Especially we want to emphasize again the recommendation to test the migration with a copy of your real data to exclude or determine any issues beforehand.

Before executing this update task, OX App Suite v7.10.0 uses the new calendar stack on top of the old database tables through a compatibility layer. As the old storage layout lacks certain functionality, not all features are functional in between the application upgrade and execution of the update task. Due to this fact, a few spots are affected where not all appointment data that the user interface allows to enter can be persisted. This includes:

* Reminders, where still only one notification prior the appointment start is possible
* Colors, that cannot be mapped to the previously used labels
* 4-byte UTF-8 characters (emojis) are not yet possible
* Secret appointments, that are still stored as private ones
* An appointment's end timezone can't be applied, if it's different from the start timezone

Operators of ''non-Galera'' MySQL setups - i.e. Master-Slave replication - can potentially speed up the migration by configuring <code>com.openexchange.calendar.migration.intermediateCommits = false</code>. Per default the migration is performed in batches that separately committed, as Galera does not cope well with large transactions. By changing the setting to <code>false</code>, a single transaction with batch-mode enabled is used.

'''Important:''' The migrating of calendar data actually leads to a duplication of that data. Also with OX App Suite v7.10.0 every new calendar data is written to both, the old and the new tables redundantly to preserve to ability to roll back to OX App Suite v7.8.4. However, only the parts can preserved that match the old data model. I.e. additional features like multiple reminders or subscriptions of external calendars (Google Calendar, SchedJoules) cannot be preserved during a rollback.

A repeated OX App Suite v7.10.0 upgrade after a former rollback to OX App Suite v7.8.4 requires to force re-execution of this update task!

AppSuite:7 10 Database Migration

2018-07-18T11:13:14Z

Choeger: /* Initial OX App Suite v7.10.0 Rollout */

{{Version|7.10.0}}

= Database Migration with OX App Suite v7.10.0 =

OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read this paper carefully to ensure a smooth and clean upgrade process.

== Change Overview ==

The most significant changes are:
* New version and configuration requirements.
* Most VARCHAR columns need to be migrated to utf8mb4 character encoding.
* A major rewrite of the calendar application requires full data migration.

We strongly recommend to thoroughly plan and test the upgrade procedure. To gain insights about update task runtimes and the expected load, our recommendation is to clone ConfigDB and the biggest UserDB and perform an isolated test upgrade that especially covers the calendar migration and character encoding changes. Update task durations can be significantly longer than with previous upgrades and the migrations might cause noticeable higher I/O load. Also some additional disk space is needed during and after the migrations.

== Database System ==

MySQL Server is supported in versions 5.6 and 5.7 with recent patch levels only and MariaDB Server 10.1 and 10.2 respectively. Support for 5.6/10.1 exists for compatibility reasons and is transitional. We recommend upgrading to 5.7/10.2 as soon as possible. Any database system upgrade must happen before App Suite is upgraded to OX App Suite v7.10.0. Please follow the respective guides of your database vendor carefully.

Different App Suite and database system versions require different configurations of the DBMS, please follow http://oxpedia.org/wiki/index.php?title=My.cnf to have your database configured in a sane way. Especially the following items require some attention with the upgrade to App Suite 7.10.0 and upgrades of the DBMS itself:

* Supported SQL modes are only <code>NO_ENGINE_SUBSTITUTION</code> and <code>NO_AUTO_CREATE_USER</code>. Starting with App Suite 7.10.0, <code>ONLY_FULL_GROUP_BY</code> is also supported for MySQL 5.7. It is still not with older versions of MySQL or any MariaDB version! To review the current value, use <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'sql_mode';</code>.
* Ensure that <code>character_set_server</code> is set to <code>utf8</code> for App Suite 7.8.x. Again the current global default value can be obtained via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'character_set_server';</code>. With 7.10.0 being fully rolled out, this setting must then be changed to <code>utf8mb4</code>. If <code>collation_server</code> is configured explicitly, it must be set to a matching value according to the character set in either case!

Note that App Suite <= 7.8.4 did not support MySQL 5.7/MariaDB 10.2 so far. While we recommend it for 7.10.0, this leaves a lack of definition during the upgrade process. We consider running 7.8.4 on top of MySQL 5.7/MariaDB 10.2 a valid scenario as long as it is transitional during the upgrade phase. Please take our configuration recommendations seriously to mitigate potential user-facing issues as far as possible.

== Upgrade Procedure ==

The upgrade to OX App Suite v7.10.0 can be performed like any other major upgrade before. However, the duration of blocking database update tasks for the mentioned charset and calendar migrations could conflict with customers’ availability demands. Therefore it is possible to decouple these special time- and resource-intensive tasks from the plain version upgrade. In this section a multi-step approach is described that performs the version upgrade before and independently from the migrations. Every step always results in a working system that is ready to serve user traffic. Some functional implications that affect user experience are outlined in the according subsections.

'''Important:''' Even though the first step leads to a basically working OX App Suite v7.10.0 environment, the subsequent steps are not optional but mandatory! Skipping the migrations will leave a few calendar features dysfunctional and can lead to issues with certain SQL queries that use explicit collations for searching and sorting. Running OX App Suite v7.10.0 in production without having all parts of the migration fulfilled is not supported – OX support will request you to complete the migration tasks when reporting issues that are not related to the migration itself.

== Initial OX App Suite v7.10.0 Rollout ==
If not done so far, upgrade your MySQL installation to a version supported with OX App Suite v7.10.0 but configure it to be compatible with OX App Suite v7.8.x as described in the “Database System” section.

Despite the fact that the two special migrations for calendar and character sets are explicitly skipped, this section assumes that the “Rolling Upgrade with breaking Hazelcast upgrade” is applied as described in [[AppSuite:Running_a_cluster#Updating_a_Cluster]]. For the application server upgrade, the common guide from [[AppSuite:UpdatingOXPackages]] can be followed.

Prepare a dedicated App Suite middleware node that will be used to perform the database update tasks. The node must not be serving any user traffic and be prepared with

* OX App Suite v7.10.0 packages
* Configuration according to the user production nodes
* The Hazelcast rolling upgrade compatibility package (see [[AppSuite:Running_a_cluster#Rolling_Upgrade_with_breaking_Hazelcast_upgrade]])
* Exclude the update tasks for both mentioned migrations (i.e. calendar and character encoding). See “Update Task Exclusion” for details.
* Execute update tasks according to your preferred strategy. More on this can be found at [[UpdateTasks]].

By default (if using the "runallupdate" tool") update tasks operate on database schemas sequentially, one at a time. All users from all contexts of a given schema are logged out and locked out. Then, DB schema changes are executed. Finally, users are unlocked and able to login again. Schemas typically contain a few thousand users (if our recommended sizing is being followed) and thus executing update tasks means bunches of a few thousand users will be affected sequentially. You will not have a full downtime. For each update task execution process the following statements hold true:

* All users got service for nearly all the time (all the time but the time where their schema is upgraded)
* For each point in time, nearly all users got service (all but the ones from the currently updated schema)
* When update tasks are completed, all users will have been affected by one "logout" - "locked out" cycle

After complete and successful update task execution, roll out OX App Suite v7.10.0 to one node after another. After complete rollout, reconfigure MySQL if appropriate as described in the “Database System” section.

=== Update Task Exclusion ===

Add the following lines to <code>/opt/open-xchange/etc/excludedupdatetasks.properties</code> or remove the leading # character if already included, so that it contains these two lines:

# Character Encoding Migration
com.openexchange.groupware.update.excludedUpdateTasks=groupware.utf8mb4

# Calendar Migration
com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask

The first line does not denote one dedicated update task, but a whole list of tasks. To make exclusion more convenient, the concept of update task namespaces has been introduced. All update tasks belonging to the character encoding migration are part of the <code>groupware.utf8mb4</code> namespace. The denoted property takes care of excluding them all at once. You can list all according tasks with the <code>/opt/open-xchange/sbin/listUpdateTaskNamespaces</code> tool.

== Character Encoding Migration ==

The default character encoding for Unicode (named character set by MySQL) of MySQL will become <code>utf8mb4</code> in the near future. MariaDB on Debian Stretch (9) already has an according default configuration set when installing it from distribution packages. So far all VARCHAR columns are supposed to store at max. 3-byte UTF-8 characters due to the nature of MySQL’s utf8 character encoding. This leads to the fact that for example emojis cannot be saved as part of any App Suite entities. In a mixed-mode scenario (App Suite considers MySQL to operate in utf8mb4 mode due to the <code>character_set_server</code> setting, while columns are specified with utf8 encoding), this leads to issues whenever certain collations during SELECT statements are enforced. To avoid such issues generally and also increase user experience by finally allowing characters from the Unicode astral plane, Open-Xchange has decided to migrate existing data structures to the utf8mb4 character encoding.

This migration can be executed before or after the calendar migration, while it is recommend to execute it before.

The upgrade procedure is basically the same as above in terms executing update tasks, while the server software is already up to date and needs no further upgrades:

* Again prepare one dedicated node that doesn’t serve any user traffic
* Remove the according namespace property from <code>excludedupdatetasks.properties</code> again, but still keep the “ChronosStorageMigrationTask”. Afterwards restart the open-xchange daemon.
* Execute update tasks according to your preferred strategy.

'''Important:''' The update tasks require a lot of tables to be copied and re-created, leading to high I/O and especially sequential read and write operations. For every copied table the needed MySQL disk space doubles during the update task, so ensure enough free space before running the migration.

== Calendar Data Migration ==

The new calendar stack in OX App Suite v7.10.0 comes along with a new data model using its very own tables in MySQL. To preserve users calendar data, an update task <code>com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask</code> has been introduced, that reads all data from the old tables, applies transformations to match the new stack and writes it into the new tables. The approach and upgrade process is described in detail at https://documentation.open-xchange.com/7.10.0/middleware/components/calendar/data_migration.html. Please read that article carefully before continuing. Especially we want to emphasize again the recommendation to test the migration with a copy of your real data to exclude or determine any issues beforehand.

Before executing this update task, OX App Suite v7.10.0 uses the new calendar stack on top of the old database tables through a compatibility layer. As the old storage layout lacks certain functionality, not all features are functional in between the application upgrade and execution of the update task. Due to this fact, a few spots are affected where not all appointment data that the user interface allows to enter can be persisted. This includes:

* Reminders, where still only one notification prior the appointment start is possible
* Colors, that cannot be mapped to the previously used labels
* 4-byte UTF-8 characters (emojis) are not yet possible
* Secret appointments, that are still stored as private ones
* An appointment's end timezone can't be applied, if it's different from the start timezone

Operators of ''non-Galera'' MySQL setups - i.e. Master-Slave replication - can potentially speed up the migration by configuring <code>com.openexchange.calendar.migration.intermediateCommits = false</code>. Per default the migration is performed in batches that separately committed, as Galera does not cope well with large transactions. By changing the setting to <code>false</code>, a single transaction with batch-mode enabled is used.

'''Important:''' The migrating of calendar data actually leads to a duplication of that data. Also with OX App Suite v7.10.0 every new calendar data is written to both, the old and the new tables redundantly to preserve to ability to roll back to OX App Suite v7.8.4. However, only the parts can preserved that match the old data model. I.e. additional features like multiple reminders or subscriptions of external calendars (Google Calendar, SchedJoules) cannot be preserved during a rollback.

A repeated OX App Suite v7.10.0 upgrade after a former rollback to OX App Suite v7.8.4 requires to force re-execution of this update task!

AppSuite:OX System Requirements

2018-07-18T07:02:25Z

Choeger: /* Important Notes */

= OX App Suite Requirements - Open-Xchange supported components overview =

The following table provides an overview about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility. This overview makes no claim to be complete.

Open-Xchange Server 6 overview tables about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility are available at [[OX_System_Requirements|OX 6 Requirements - Open-Xchange supported components overview]]

Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]

== Hardware Requirements ==
=== General Assumptions ===
Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.

This means in particular, but not only:

* Infrastructure is "quasi-static". We don't need to take into account things like VMs coming and going dynamically, dynamic IPs, volatile ("ephemeral") data
* "Database as a service" is not allowed. This typically is a highly customized "MySQL like" storage engine, and not a true MySQL, and we can't control flavor, version, setup, etc. If need for configuration changes is identified, we won't be able to change anything.

So to summarize: we expect any virtualized platform to behave and work just like a well-known non-virtualized / physical platform.

Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.

Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.

'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''

=== High Level Design / OS setup ===
Operate services separately (USM, Document/Image Converters) as described in Cluster Setup.

Clocks between all nodes must be synchronized (e.g. via NTP).

Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.

Platform Architecture: 64 bit versions (x84_64) of the supported [[#Software Requirements | Linux distributions]]

=== Node Sizing ===
* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)
* 4 CPU cores (virtual, physical or hyperthreads)
* Disk space
** 5 GB for OS and software
** <code>2 * system memory</code> of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps

=== Untested/Unsupported Deployments ===
* Changes to Garbage Collector settings
* Running in containerized environments (Docker, rkt)
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration
* Cloud platform services (PaaS) like database systems (for example AWS RDS)
* Multi-site active-active

== Software Requirements ==

=== Linux Distributions ===

OX App Suite is available as Linux packages for the following distributions:

{|border="2" rules="all" align="left">
|'''Distribution'''
|'''Versions'''
|'''Derivates'''
|-
| 
| 
| 
|-
|Suse Linux Enterprise Server
|12
|None
|-
|Red Hat Enterprise Linux
|6,7
|CentOS
|-
|Debian
|8 (Jessie), 9 (stretch)
|None
|-
|}

=== Java ===

OX App Suite Middleware requires OpenJDK headless JRE 8 or 9.

'''Please note:''' For Debian 8 (Jessie) OpenJDK 8 is only available via the [https://packages.debian.org/search?keywords=jessie-backports jessie-backports] repository.

=== Databases ===

OX App Suite uses MySQL with the InnoDB storage engine as its primary data store. The following vendors and products are supported.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''Versions'''
|-
| 
| 
| 
|-
|Oracle
|MySQL Community Edition, Standard Edition, Enterprise Edition
|[5.6.x, 5.7.x]
|-
|MariaDB
|MariaDB Server, Galera Cluster
|[10.1.x, 10.2.x]
|-
|Percona
|XtraDB Cluster
|[5.6.x, 5.7.x]
|-
|}

=== Important Notes ===

* For some Linux distributions the included MySQL/MariaDB packages are too old to be used with App Suite. It is mandatory then to install a supported version from upstream package sources. Possible sources are the official vendor repositories of MySQL, MariaDB or Percona as well as for example Red Hat Software Collections.
* Required MySQL configuration differs between App Suite 7.8.4 and 7.10.0 and also between the different database systems in terms of SQL modes. See [[My.cnf]] for details.
* For upgrades to App Suite 7.10.0 a comprehensive database upgrade guide exists: [[AppSuite:7_10_Database_Migration]]

== File Storage ==

=== Temporary Data ===

OX App Suite stores temporary files in the local file system, e.g. for spooling of uploaded data. Any file system supported by the installed JRE is suitable.

=== Persistent Data ===

Persistent data like OX Drive files, PIM attachments etc. needs to be stored in a distributed file system that is available from all server nodes. For single-node setups a local file system mount point can be used, small to mid-scale setups can be powered by NFS. For large-scale setups object storages should be considered.

==== Object Storages ====

OX App Suite ships with different optional adapters to support object storages.

{|border="2" rules="all" align="left">
|'''Vendor'''
|'''Product'''
|'''API'''
|'''Remarks'''
|-
| 
| 
| 
| 
|-
|Amazon
|AWS S3
|S3 HTTP API
|See also http://oxpedia.org/wiki/index.php?title=AppSuite:S3_File_Store
|-
|CEPH
|RadosGW
|S3 HTTP API
|See also http://oxpedia.org/wiki/index.php?title=AppSuite:S3_File_Store
|-
|Scality
|Scality RING
|Sproxyd HTTP API
|See also http://oxpedia.org/wiki/index.php?title=AppSuite:Scality_File_Store
|-
|OpenStack
|Swift
|Object Storage API V1
|Support for Swift is experimental and could be removed again in the future. See also http://oxpedia.org/wiki/index.php?title=AppSuite:Swift_File_Store
|-
|}

== Desktop Browser (Minimum display resolution: 1024 x 768)==

{|border="2" rules="all" align="left">
|'''Browser'''
|'''OX App Suite User Front-End'''
|-
| 
| 
|-
|Microsoft Internet Explorer 10/11
|v7.6.3
|-
|Microsoft Internet Explorer 11/Edge
|v7.8.4, v7.10.0
|-
|Mozilla Firefox (latest & previous version)
|v7.8.4, v7.10.0
|-
|Google Chrome (latest & previous version)
|v7.8.4, v7.10.0
|-
|Apple Safari (10.01 & 10.03; Mac OS X only)
|v7.8.4, v7.10.0
|-
|}

== Mobile Device Support==

{|border="2" rules="all" align="left">
|'''Mobile Device'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|iPhone on iOS 10 / iOS 11
|Safari
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|-
|Smartphone on Android 4.1 or later
|Chrome (latest & previous version)
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|}

== Tablet Support==

{|border="2" rules="all" align="left">
|'''Tablet'''
|'''Supported Browser'''
|'''OX App Suite User Front-End'''
|'''Minimum Speed Requirements'''
|-
| 
| 
| 
| 
|-
|Apple iPad (all devices) on iOS 10 / iOS 11
|Safari
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|-
|Tablets on Android 4.1 or later
|Chrome (latest & previous version)
|v7.8.4, v7.10.0
|3G connections (512/256kBit/s, 350ms latency)
|}

== Calendar/Contact synchronization Apple Mac OS X ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Mac OS X 10.11 (El Capitan)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|macOS 10.12, 10.13 (Sierra & High Sierra)
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Calendar/Contact synchronization Apple iOS ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|Calendar synchronization with CalDAV
|Contacts synchronization with CardDAV
|-
| 
| 
| 
|-
|Apple iOS 10 / iOS 11
|[[File:check.gif]]
|[[File:check.gif]]
|-
|}

== Mobility Solution - Supported- Platforms, Features and Devices ==

{|border="2" rules="all" align="left">
|'''Feature/Technology/Device'''
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)
|-
| 
| 
|-
|Exchange Active Sync 2.5
|[[File:check.gif]]
|-
|Exchange Active Sync 12.1
|[[File:check.gif]]
|-
| 
| 
|-
|Access and creation of emails
|[[File:check.gif]]
|-
|Personal PIM folder
|[[File:check.gif]]
|-
|Public and Shared PIM folder
|[[File:cross.gif]]
|-
|Global address book
|[[File:check.gif]]
|-
|Push E-Mail
|[[File:check.gif]]
|-
| 
| 
|-
|Windows Phone 8 (latest & previous minor versions), Windows Phone 10 (latest & previous minor versions)
|[[File:check.gif]]
|-
|Apple iOS 10 / iOS 11
|[[File:check.gif]]
|-
|Android 4.1 or later
|[[File:check.gif]]
|-
|}

== OX Drive for Clients ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|OX Drive for Windows
|Latest versions of Windows 8, latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|-
|OX Drive for Mac OS
|Mac OS X 10.11 (El Capitan), macOS 10.12, 10.13 (Sierra & High Sierra)
|-
|OX Drive for iOS
|Apple iOS 10, Apple iOS 11
|-
|OX Drive for Android
|Smartphone on Android 4.1 or later with Chrome (latest & previous version), Tablets on Android 4.1 or later with Chrome (latest & previous version)
|-
|}

== OX Mail App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|OX Mail for iOS
|Apple iOS 10, Apple iOS 11
|-
|OX Mail for Android
|Smartphone on Android 4.3 or later
|-
|}

== OX Mail App v2 ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Main_Page_Quickinstall#Quick_Installation_Guide OX App Suite]
|OX App Suite v7.8.4 or later
|-
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Mobile_API_Facade Mobile API Facade]
|Mobile API Facade v1.0.2 or later (until OX App Suite v7.8.4) Mobile API Facade v1.2.0 or later (from OX App Suite v7.10.0)
|-
|Push Notification Package
|Package "open-xchange-mobile-api-facade-push-certificates" (available to App Suite licensees only)
|-
|OX Mail App v2.0 for iOS
|Apple iOS 9.3, iOS 10, iOS 11 Server reachable via TLS 1.2
|-
|OX Mail App v2.0 for Android
|Android 5.0 (Lollipop) or higher Server reachable via TLS 1.2
|-
|}

== OX Sync App ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|OX Sync App for Android
|Smartphone on Android 4.0 or later
|-
|}

== OX Guard ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|'''System / Platform / User Interface'''
|-
| 
| 
|-
|OX App Suite
|OX Guard since v2.6.0: OX App Suite v7.8.3 OX Guard since v2.8.0: OX App Suite v7.8.4 OX Guard since v2.10.0: OX App Suite v7.10.0
|-
|Mobile Device and Tablet Support
|Apple iPhone on iOS 10 / iOS 11: Safari (latest version & previous version) Smartphone on Android 4.1 or later: Chrome (latest & previous version) Apple iPad (all devices) on iOS 10 / iOS 11: Safari Safari (latest version & previous version) Tablets on Android 4.1 or later: Chrome (latest & previous version)
|-
|}

== eM Client for OX App Suite ==

{|border="2" rules="all" align="left">
|'''Requirement'''
|[http://oxpedia.org/wiki/index.php?title=AppSuite:EM_Client_for_OX_App_Suite '''eM Client for OX App Suite''']
|-
| 
| 
|-
|OX App Suite
|OX App Suite v7.8.4, OX App Suite v7.10.0
|-
|Client PC operating system
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)
|-
|}

[[Category: OX7]]
[[Category: AppSuite]]

AppSuite:Configuring portal plugins

2018-06-26T06:03:35Z

Choeger:

{{Stability-stable}}
{{VersionFrom|7.4.0}}

= Configuring portal plugins =

''Synopsis:'' This article covers how to configure which plugins ("tiles") are shown, whether they are mandatory or just suggested to the user.

__TOC__

== Configuring the portal ==

When running OX AppSuite you may want to specify a starting configuration for which tiles the portal shows and whether certain tiles are mandatory or not. This is especially useful when you are introducing your own tile implementations. To make this possible, the portal consists of three types of tiles: User tiles, eager tiles and protected tiles. User tiles are tiles that the user added herself to the portal page, eager tiles are those suggested by the installation which can be removed and protected tiles are set by the backend.

In order to specify a tile, you will have to know about the configuration data to enter. You can use an appsuite installation to do that. If you want to configure a tile as eager or protected, navigate to the settings area of the portal page, add the tile you want and, in the JS console, enter:

require("settings!io.ox/portal").get("widgets/user")

and in the list find the tile you want to suggest to or force on your users. As an example, we'll use the birthday widget:

birthdays_0: Object
color: "lightgreen"
enabled: true
id: "birthdays_0"
index: 6
inverse: false
plugin: "plugins/portal/birthdays/register"
props: Object
type: "birthdays"

In order to configure widgets on the backend we have to turn the above into a valid YAML structure:

birthdays_0:
color: "lightgreen" # one of black, red, orange, lightgreen,
# green, lightblue, blue, purple, pink, gray
enabled: true # Has to be true
index: "first" # Where the widget is supposed to show up.
# Possible values are numbers, "first" or
# "last"
inverse: false # If true, the color is applied to the body
# of the tile and not the title. Can highlight
# particular tiles
plugin: "plugins/portal/birthdays/register" # The source file that contains the tile code
type: "birthdays" # The id of the widget type. Not the id above
# has to have the form [type]_[someNumber]

Now we can use this snippet to configure the birthday widget in a variety of ways

== I want to suggest a widget, but the user can remove it, if they don't like it ==

For this, you can use the "eager" configuration method. Not that if you specify an eager or protected widget, all default widgets from Open-Xchange will not be configured as defaults anymore, so you might want to configure them as eager tiles as well. But let's stick to the birthday widget for now.

* Add a file /opt/open-xchange/etc/settings/portal.yml

io.ox/portal//widgets/eager/gen_0:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

This means the widget will be enabled for users, but users can still disable it. If you want to, at a later time and since you've made significant improvements to the tile, want to show it to the user again, you have to increase the "generation" of the widget configuration and offer it again:

io.ox/portal/:
generation: 1

io.ox/portal//widgets/eager/gen_0:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

io.ox/portal//widgets/eager/gen_1:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

All the "gen_[number]" entries up the tie io.ox/portal//generation will be used for this configuration. If a tile is deleted it is deleted only in that generation so can be reintroduced in a later portal configuration generation. If you want to keep the default tiles as used as a fallback for App Suite, you need this configuration to start out with:

io.ox/portal//widgets/eager/gen_0:
mail_0:
plugin: 'plugins/portal/mail/register'
color: 'blue'
enabled: true
index: 1
calendar_0:
plugin: 'plugins/portal/calendar/register'
color: 'red'
enabled: true
index: 2
tasks_0:
plugin: 'plugins/portal/tasks/register'
color: 'green'
enabled: true
index: 3
birthdays_0:
plugin: 'plugins/portal/birthdays/register'
color: 'lightgreen'
enabled: true
index: 4
twitter_0:
plugin: 'plugins/portal/twitter/register'
color: 'pink'
enabled: true
index: 5
linkedin_0:
plugin: 'plugins/portal/linkedin/register'
color: 'lightblue'
enabled: true
index: 6

And then modify this as wanted for your deployment. Note, that LikedIn support was removed with version 7.10.

== Forcing a tile ==

Similarly to the eager tiles, tiles can be "protected", i.e. they can not be moved, removed and disabled. The configuration for this looks like that:

io.ox/portal//widgets/protected:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"

If you want to allow movement of the widget, you can enable this in the following way:

io.ox/portal//widgets/protected:
birthdays_0:
color: "lightgreen"
enabled: true
index: "first"
inverse: false
plugin: "plugins/portal/birthdays/register"
type: "birthdays"
changeable:
index: true

In which case, users will be allowed to move the tile.

One caveat in all this: After changing any of the above configuration, you will have to reload the UI *twice*, since App Suite uses read-through caching for the settings data.

== Disabling a tile completely ==
The combination of making a tile both protected and disabling it makes it impossible for the user to enable it. From 7.6.0 on, this means it is not shown in the settings either. Before that, it was greyed out but still present.

io.ox/portal/:
widgets:
protected:
quota_0:
color: "red"
id: "quota_0"
enabled: false
index: 1
inverse: false
plugin: "plugins/portal/quota/register"
type: "quota"

[[Category:Backend]][[Category:AppSuite]]

[[Category:Portal]]

[[Category:Administrator]][[Category:Developer]]

AppSuite:Architecture Overview

2018-06-20T05:53:18Z

Choeger:

__NOTOC__
This page gives an overview of the most important internal components, plugin capabilities, public interfaces (APIs) and data communication streams of the Open-Xchange server.

[[File:appsuite_architecture_diagram_3.png|1200px]]

=Frontend and client based communication flow =
*'''1''' All communication from and to the users client is purely based on HTTP. It is strongly recommended to use only encrypted HTTPS. For security reasons, some modules require HTTPS connections in the default configuration. The HTTP(S) communication is terminated at Apache.

*'''2''' Within Apache, the mod_proxy_http module is used to forward the request to the OX server. Apache can also be used to configure session stickiness and load balancing in clustered environments.

*'''3''' OX Web UI
** The [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API] is the core API for all user functionality. Every function of the Web UI is using this API. In addition to that, all possible user functionality is available via this API and can be used from external applications as well. It is based on JSON via HTTP(S).
** [http://oxpedia.org/wiki/index.php?title=Portal:AppSuite_UI Web UI Documentation]
** [[HTTP_API_Examples|Programming Example]], how to use this API to build an Email widget, accessing the HTTP API

*'''4''' The OXtender for Business Mobility is a server based Active Sync Implementation. The "Microsoft Exchange Active Sync" protocol supports Push via HTTPS, therefore the email backend needs to send push events to the OX server. Details, see: [[OXtender for Business Mobility Installation Guide]] and [[OX_EMail_Push_Introduction|Email Push Introduction]]. Serverside, the synchronization makes use of the "Universal Sync Module (USM)", which is a server bundle containing the synchronization logic for several clients. It also communicates via HTTP(S) transporting JSON objects.

*'''5''' The [[OXtender 2 for Microsoft Outlook]] is a MAPI plugin, installed in the Outlook client to synchronize data between Outlook and the OX server. It makes use of the same HTTP(S) and JSON based communication to the Universal Sync Module (USM), like Active Sync.

*'''6''' [[Caldav carddav Bundles|CalDAV and CardDAV]] interfaces are available to synchronize calendars and address books with Apple OS X and iOS applications as well as Thunderbird: [[CalDAVClients|CalDAV Clients]] and [[CardDAVClients|CardDAV Clients]].

*'''7''' A WebDAV implementation provides the possibility to access the documents in the Files-module directly via any WebDAV client, like the Windows Explorer.

=Administration, provisioning and operations related components and communication flow=
*'''11''' Data Migration and Im-/Export of user data can be done via automated tools, using these interfaces:
** [[Using the import servlet]], [[Building an importer]]
** [[Using the export servlet]], [[Building an exporter]], [[Export_ical/vcard| iCal/vCard]]
** A tool is available to upload data from Outlook profiles or PST files to OX: [http://oxpedia.org/wiki/index.php?title=OX_Outlook_Uploader Outlook Uploader]

*'''12''' All provisioning tasks, like creating and editing users can be done with [[AppSuite:AdminGuide_7.8.4#OX_App_Suite_Management_.28CLT.29|Commandline tools]]. The command line tools make use of the Java RMI API internally.

*'''13''' The native, central provisioning API is available via Java RMI and split into the [http://software.open-xchange.com/OX6/doc/RMI/admin-core/ Core API] and the [http://software.open-xchange.com/OX6/doc/RMI/admin-hosting/ HostingAPI].

*'''14''' Central control panels and billing systems, which are not implemented in Java, can use the [[Open-Xchange-SOAP|SOAP API]].
** For OX as a Service, there's a specific [[OX_as_a_Service_Provisioning_using_SOAP|SOAP API documentation]]

*'''15''' Authentication is implementable via highly customizable plugins, different standard and custom implementations are available
**[[Authentication IMAP Plugin description| IMAP]]
** LDAP
** Database
** custom

*'''16''' Monitoring the OX application is done via JMX, for a description see [[OX monitoring interface]], or a commandline tool
** An example how to use the monitoring interface is available as pre-built Scripts for the monitoring tool Munin: [[OX munin scripts]]

=Backend related components and communication flow=
*'''21''' All OX-internal data - users, contacts, calendars, tasks and document metadata is stored in a MySQL Database, accessed via JDBC
**'''22''' Native MySQL contacts storage

*'''23''' Other sources for contacts than the MySQL storage can also be used. For this an OSGi bundle needs to be implemented, overriding the standard contact storage.
** An implementation using LDAP is publicly available
** Several custom implementations are available on request or can be implemented by partners

*'''24''' Email storage is accessed through the pluggable [http://software.open-xchange.com/OX6/doc/mal/ Mail Abstraction Layer API]
** The default implementation uses IMAP
** Sending Emails is done via SMTP
** For Active Sync or Outlook the email backend needs to send push requests to the OX server, for details see [[OX_EMail_Push_Introduction|Email Push Introduction]]
** Several custom implementations are available on request or can be implemented by partners

*'''25''' Documents in the Files module are accessed via an API, which allows customized implementations.
** The default in large environments is to use NFS
** In small environments the local filesystem is used
** [http://www.scality.com/ Scality] is also available
** Several custom implementations are available on request or can be implemented by partners

=Social/Public Data related components, plugins and communication flow=

A subscription based plugin system allows to access data from external systems like webmail systems or social networks. The underlying concept is called SocialOX and a list of some plugins can be found here: [[SupportedCrawler]]. The integrations of messaging, contacts and calendars are done via the official API of the respective 3rd-party-service if there is one. For authentication, OAuth is used for security and privacy control if available. All plugins use HTTP(S) connections to the external services only. Access to the external email systems is done via IMAP(S) or POP3(S), depending on the service.

*'''31''' For subscription to an external calendar a plugin to subscribe to Google Calendar is available.

*'''32''' Supported external messaging services are Twitter and SMS/MMS.

*'''33''' Contacts can be imported from Xing, LinkedIn (removed since 7.10.0), MSN/Windows Live/Outlook.com, Yahoo and Google.

*'''34''' External email accounts can be integrated via POP3(S) or IMAP(S)
** There are pre-configured settings for many popular services so that users only need to enter their e-mail address and password.
** Look here how to [[install and configure the mail-account plugin]].

* '''35''' RSS feeds are loaded remotely, filtered for exploits and can be read in the UI

* '''36''' Image services like Flickr and Tumblr are integrated directly into the UI, bypassing the backend completely. Authentication is handled via OAuth.

=Publicly Available Plugins=
* An overview of the existing public plugins can be found here: [[Open-Xchange Plugin Overview]]. Many others are available on request or through partners.

Open-Xchange Plugin Overview

2018-03-16T10:07:25Z

Choeger: Redirected page to AppSuite:Open-Xchange Plugin Overview

#REDIRECT [[AppSuite:Open-Xchange Plugin Overview]]

AppSuite:Open-Xchange Plugin Overview

2018-03-16T10:05:21Z

Choeger: Choeger moved page OX6:Open-Xchange Plugin Overview to AppSuite:Open-Xchange Plugin Overview

= Overview of available Open-Xchange Plugins =

== Core Plugins ==

These plugins are part of the Open-Xchange Server Core platform.

{| border="1" cellpadding="3" cellspacing="0"
!style="width:230px" align="left" |Name
!style="width:230px" align="left" |Description
!align="left" |Documentation
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-authentication-ldap]
|Authentication against LDAP server
|
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-authentication-imap]
|Authentication against IMAP server
|[[Authentication_IMAP_Plugin_description|Authentication imap plugin description]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-admin-plugin-contextrestore]
|Plugin to restore one or more contexts from a complete database dump
|http://software.open-xchange.com/OX6/doc/OX6-Installation-and-Administration.pdf
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-dataretention / open-xchange-dataretention-csv]
|Module to be used for data retention (german: Vorratsdatenspeicherung)
|open-xchange-dataretention-csv is an example implementation of the data retention service
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-commons-logging-log4j / open-xchange-log4j]
|These packages must be installed when Open-Xchange should use syslog
|[[Syslog_Configuration|Syslog configuration]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-contacts-ldap]
|Integrate LDAP address book into Open-Xchange public folder tree
|http://software.open-xchange.com/OX6/doc/OX6-Installation-and-Administration.pdf
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-subscribe-crawler]
|The open-xchange Social OX PlugIn bundle to subscribe/import data
|[[CrawlerArchitecture|Architecture of the Social OX PlugIn bundle]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-upsell-multiple]
|Implementing an up sell layer in Open-Xchange
|[[Upsell|Upsell package description]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-report-client]
|Tool to display and report the amount of users and contexts in the Open-Xchange environment
|[[OXReportClient|Report Client description]]
|-
|[http://software.open-xchange.com/OX6/OXtender-stable/OXUpdater/ open-xchange-outlook-updater]
|Updater server bundle to download OXtender directly from Open-Xchange GUI
|
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-passwordchange-script]
|Use an external command to change a password
|[[ChangePasswordExternal|Example Script]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-publish-microformats]
|Publishing of Open-Xchange internal data structures like contacts, documents.
|[[Open-Xchange_Publishing|Publishing Data with Open-Xchange]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-calendar-printing]
|Generating printviews of calendar items
|[[Open-Xchange_Publishing|Publishing Data with Open-Xchange]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-audit]
|User action tracking bundle
|[[OXAudit|Audit bundle description]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-push-mailnotify]
|Accepting external new mail notifications
|[[MailNotify_Bundle|Mail Notification (Push) with Open-Xchange]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-push-imapidle]
|Mail push using IMAP IDLE
|[[MailPushIMAPIDLE_Bundle|Mail Notification (Push) with Open-Xchange]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-subscribe-msn]
|MSN subscription
|[[MSN_Bundles|Windows Live / MSN]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-messaging-twitter]
|Twitter messaging
|[[Twitter_Bundles|Twitter]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-subscribe-linkedin]
|LinkedIn subscription
|[[LinkedIn_Bundles|LinkedIn]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-admin-plugin-reseller]
|Reseller provisioning plugin
|[[Reseller_Bundle|Install the Open-Xchange Reseller package]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory]
|Bundles implementing CalDAV and CardDAV functionalities for Open-Xchange
|[[Caldav carddav Bundles|Using the CalDAV and CardDAV bundles]]
|-
|[http://software.open-xchange.com/OX6/stable/ open-xchange-messaging-sms open-xchange-messaging-sms-gui open-xchange-messaging-sms-gui-theme-default]
|Bundles offering the SMS/MMS interfaces for Open-Xchange
|[[Custom_SMS_MMS_Implementation|Developing a SMS/MMS gateway implementation]]
|}

----

== Additional Plugins ==

The plugins listed here are not - yet - part of the Core platform and may or may not ever be part of the Open-Xchange Core platform.

These plugins are not supported by Open-Xchange with the exception of concrete projects. Please [http://www.open-xchange.com/en/contactus contact us] for more details.

{| border="1" cellpadding="3" cellspacing="0"
!style="width:230px" align="left" |Name
!style="width:230px" align="left" |Description
!align="left" |Documentation
|-
|}

----

== Custom Plugins ==

The following list consists of plugins, that Open-Xchange developed for specific customers. It is an overview of what is possible to do with the Open-Xchange integration platform.

If you want Open-Xchange to develop a specific plugin for you, please [http://www.open-xchange.com/en/contactus contact us] for more details.

{| border="1" cellpadding="3" cellspacing="0"
!style="width:150px" align="left" |Name
!align="left" |Description
|-
|MAL
|Plugin which replaces the standard imap/smtp plugin to access the mail store with a customer specific plugin, e.g. directly access a [http://en.wikipedia.org/wiki/Maildir maildir] mailstore.
|-
|Upsell
|If the example upsell plugin does not fit your needs or has some missing functionality, do not hesitate to contact us.
|-
|Spam
|It's possible to integrate the built in mark as SPAM/HAM functionality into almost any solution.
|-
|Authentication
|Authentication can be done against every system that allows to specify a username/password combination.
|-
|Migration from OX5 to OX6
|Migration plugin that updates the user passwords in OX6 Database after a successful login to the OX5 LDAP service. That way, passwords can be migrated automatically from any LDAP to OX6 database.
|-
|Corporate Integration: EasyLogin
|The EasyLogin mechanism allows to login into Open-Xchange from other applications without specifying username and password again.
|-
|Corporate Integration: ConfigJump
|Integrate your own configuration application in the Open-Xchange settings tree.
|-
|UI Customization
|A lot of customization can be done in the Open-Xchange UI. Starting from themes to the integration of custom modules and functions.
|}

[[Category: OX6]]

AppSuite:Architecture Overview

2018-03-16T09:15:49Z

Choeger:

__NOTOC__
This page gives an overview of the most important internal components, plugin capabilities, public interfaces (APIs) and data communication streams of the Open-Xchange server.

[[File:appsuite_architecture_diagram_3.png|1200px]]

=Frontend and client based communication flow =
*'''1''' All communication from and to the users client is purely based on HTTP. It is strongly recommended to use only encrypted HTTPS. For security reasons, some modules require HTTPS connections in the default configuration. The HTTP(S) communication is terminated at Apache.

*'''2''' Within Apache, the mod_proxy_http module is used to forward the request to the OX server. Apache can also be used to configure session stickiness and load balancing in clustered environments.

*'''3''' OX Web UI
** The [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API] is the core API for all user functionality. Every function of the Web UI is using this API. In addition to that, all possible user functionality is available via this API and can be used from external applications as well. It is based on JSON via HTTP(S).
** [http://oxpedia.org/wiki/index.php?title=Portal:AppSuite_UI Web UI Documentation]
** [[HTTP_API_Examples|Programming Example]], how to use this API to build an Email widget, accessing the HTTP API

*'''4''' The OXtender for Business Mobility is a server based Active Sync Implementation. The "Microsoft Exchange Active Sync" protocol supports Push via HTTPS, therefore the email backend needs to send push events to the OX server. Details, see: [[OXtender for Business Mobility Installation Guide]] and [[OX_EMail_Push_Introduction|Email Push Introduction]]. Serverside, the synchronization makes use of the "Universal Sync Module (USM)", which is a server bundle containing the synchronization logic for several clients. It also communicates via HTTP(S) transporting JSON objects.

*'''5''' The [[OXtender 2 for Microsoft Outlook]] is a MAPI plugin, installed in the Outlook client to synchronize data between Outlook and the OX server. It makes use of the same HTTP(S) and JSON based communication to the Universal Sync Module (USM), like Active Sync.

*'''6''' [[Caldav carddav Bundles|CalDAV and CardDAV]] interfaces are available to synchronize calendars and address books with Apple OS X and iOS applications as well as Thunderbird: [[CalDAVClients|CalDAV Clients]] and [[CardDAVClients|CardDAV Clients]].

*'''7''' A WebDAV implementation provides the possibility to access the documents in the Files-module directly via any WebDAV client, like the Windows Explorer.

=Administration, provisioning and operations related components and communication flow=
*'''11''' Data Migration and Im-/Export of user data can be done via automated tools, using these interfaces:
** [[Using the import servlet]], [[Building an importer]]
** [[Using the export servlet]], [[Building an exporter]], [[Export_ical/vcard| iCal/vCard]]
** A tool is available to upload data from Outlook profiles or PST files to OX: [http://oxpedia.org/wiki/index.php?title=OX_Outlook_Uploader Outlook Uploader]

*'''12''' All provisioning tasks, like creating and editing users can be done with [http://software.open-xchange.com/OX6/doc/OX6-Provisioning/ Commandline tools]. The command line tools make use of the Java RMI API internally.

*'''13''' The native, central provisioning API is available via Java RMI and split into the [http://software.open-xchange.com/OX6/doc/RMI/admin-core/ Core API] and the [http://software.open-xchange.com/OX6/doc/RMI/admin-hosting/ HostingAPI].

*'''14''' Central control panels and billing systems, which are not implemented in Java, can use the [[Open-Xchange-SOAP|SOAP API]].
** For OX as a Service, there's a specific [[OX_as_a_Service_Provisioning_using_SOAP|SOAP API documentation]]

*'''15''' Authentication is implementable via highly customizable plugins, different standard and custom implementations are available
**[[Authentication IMAP Plugin description| IMAP]]
** LDAP
** Database
** custom

*'''16''' Monitoring the OX application is done via JMX, for a description see [[OX monitoring interface]], or a commandline tool
** An example how to use the monitoring interface is available as pre-built Scripts for the monitoring tool Munin: [[OX munin scripts]]

=Backend related components and communication flow=
*'''21''' All OX-internal data - users, contacts, calendars, tasks and document metadata is stored in a MySQL Database, accessed via JDBC
**'''22''' Native MySQL contacts storage

*'''23''' Other sources for contacts than the MySQL storage can also be used. For this an OSGi bundle needs to be implemented, overriding the standard contact storage.
** An implementation using LDAP is publicly available
** Several custom implementations are available on request or can be implemented by partners

*'''24''' Email storage is accessed through the pluggable [http://software.open-xchange.com/OX6/doc/mal/ Mail Abstraction Layer API]
** The default implementation uses IMAP
** Sending Emails is done via SMTP
** For Active Sync or Outlook the email backend needs to send push requests to the OX server, for details see [[OX_EMail_Push_Introduction|Email Push Introduction]]
** Several custom implementations are available on request or can be implemented by partners

*'''25''' Documents in the Files module are accessed via an API, which allows customized implementations.
** The default in large environments is to use NFS
** In small environments the local filesystem is used
** [http://www.scality.com/ Scality] is also available
** Several custom implementations are available on request or can be implemented by partners

=Social/Public Data related components, plugins and communication flow=

A subscription based plugin system allows to access data from external systems like webmail systems or social networks. The underlying concept is called SocialOX and a list of some plugins can be found here: [[SupportedCrawler]]. The integrations of messaging, contacts and calendars are done via the official API of the respective 3rd-party-service if there is one. For authentication, OAuth is used for security and privacy control if available. All plugins use HTTP(S) connections to the external services only. Access to the external email systems is done via IMAP(S) or POP3(S), depending on the service.

*'''31''' For subscription to an external calendar a plugin to subscribe to Google Calendar is available.

*'''32''' Supported external messaging services are Twitter and SMS/MMS.

*'''33''' Contacts can be imported from Xing, LinkedIn (removed since 7.10.0), MSN/Windows Live/Outlook.com, Yahoo and Google.

*'''34''' External email accounts can be integrated via POP3(S) or IMAP(S)
** There are pre-configured settings for many popular services so that users only need to enter their e-mail address and password.
** Look here how to [[install and configure the mail-account plugin]].

* '''35''' RSS feeds are loaded remotely, filtered for exploits and can be read in the UI

* '''36''' Image services like Flickr and Tumblr are integrated directly into the UI, bypassing the backend completely. Authentication is handled via OAuth.

=Publicly Available Plugins=
* An overview of the existing public plugins can be found here: [[Open-Xchange Plugin Overview]]. Many others are available on request or through partners.

AppSuite:Architecture Overview

2018-03-16T08:59:19Z

Choeger:

__NOTOC__
This page gives an overview of the most important internal components, plugin capabilities, public interfaces (APIs) and data communication streams of the Open-Xchange server.

[[File:appsuite_architecture_diagram_3.png|1200px]]

=Frontend and client based communication flow =
*'''1''' All communication from and to the users client is purely based on HTTP. It is strongly recommended to use only encrypted HTTPS. For security reasons, some modules require HTTPS connections in the default configuration. The HTTP(S) communication is terminated at Apache.

*'''2''' Within Apache, the mod_proxy_http module is used to forward the request to the OX server. Apache can also be used to configure session stickiness and load balancing in clustered environments.

*'''3''' OX Web UI
** The [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API] is the core API for all user functionality. Every function of the Web UI is using this API. In addition to that, all possible user functionality is available via this API and can be used from external applications as well. It is based on JSON via HTTP(S).
** [http://oxpedia.org/wiki/index.php?title=Portal:AppSuite_UI Web UI Documentation]
** [[HTTP_API_Examples|Programming Example]], how to use this API to build an Email widget, accessing the HTTP API

*'''4''' The OXtender for Business Mobility is a server based Active Sync Implementation. The "Microsoft Exchange Active Sync" protocol supports Push via HTTPS, therefore the email backend needs to send push events to the OX server. Details, see: [[OXtender for Business Mobility Installation Guide]] and [[OX_EMail_Push_Introduction|Email Push Introduction]]. Serverside, the synchronization makes use of the "Universal Sync Module (USM)", which is a server bundle containing the synchronization logic for several clients. It also communicates via HTTP(S) transporting JSON objects.

*'''5''' The [[OXtender 2 for Microsoft Outlook]] is a MAPI plugin, installed in the Outlook client to synchronize data between Outlook and the OX server. It makes use of the same HTTP(S) and JSON based communication to the Universal Sync Module (USM), like Active Sync.

*'''6''' [[Caldav carddav Bundles|CalDAV and CardDAV]] interfaces are available to synchronize calendars and address books with Apple OS X and iOS applications as well as Thunderbird: [[CalDAVClients|CalDAV Clients]] and [[CardDAVClients|CardDAV Clients]].

*'''7''' A WebDAV implementation provides the possibility to access the documents in the Files-module directly via any WebDAV client, like the Windows Explorer.

=Administration, provisioning and operations related components and communication flow=
*'''11''' Data Migration and Im-/Export of user data can be done via automated tools, using these interfaces:
** [[Using the import servlet]], [[Building an importer]]
** [[Using the export servlet]], [[Building an exporter]], [[Export_ical/vcard| iCal/vCard]]
** A tool is available to upload data from Outlook profiles or PST files to OX: [http://oxpedia.org/wiki/index.php?title=OX_Outlook_Uploader Outlook Uploader]

*'''12''' All provisioning tasks, like creating and editing users can be done with [http://software.open-xchange.com/OX6/doc/OX6-Provisioning/ Commandline tools]. The command line tools make use of the Java RMI API internally.

*'''13''' The native, central provisioning API is available via Java RMI and split into the [http://software.open-xchange.com/OX6/doc/RMI/admin-core/ Core API] and the [http://software.open-xchange.com/OX6/doc/RMI/admin-hosting/ HostingAPI].

*'''14''' Central control panels and billing systems, which are not implemented in Java, can use the RMI API via the [http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html SOAP API], examples of its usage can be found [[Open-Xchange-SOAP | here]].
** Standard integration via SOAP is available for OPWV Directory
** for Parallels Operations Automation see [[PAIntegrationGuide| PA integration guide]]
** for Parallels Plesk Panel see [[Plesk_Integration|Plesk integration guide]]
** for cPanel see [[Open-Xchange_cPanel_Installation| cPanel installation]]

*'''15''' Authentication is implementable via highly customizable plugins, different standard and custom implementations are available
**[[Authentication IMAP Plugin description| IMAP]]
** LDAP
** Database
** custom

*'''16''' Monitoring the OX application is done via JMX, for a description see [[OX monitoring interface]], or a commandline tool
** An example how to use the monitoring interface is available as pre-built Scripts for the monitoring tool Munin: [[OX munin scripts]]

=Backend related components and communication flow=
*'''21''' All OX-internal data - users, contacts, calendars, tasks and document metadata is stored in a MySQL Database, accessed via JDBC
**'''22''' Native MySQL contacts storage

*'''23''' Other sources for contacts than the MySQL storage can also be used. For this an OSGi bundle needs to be implemented, overriding the standard contact storage.
** An implementation using LDAP is publicly available
** Several custom implementations are available on request or can be implemented by partners

*'''24''' Email storage is accessed through the pluggable [http://software.open-xchange.com/OX6/doc/mal/ Mail Abstraction Layer API]
** The default implementation uses IMAP
** Sending Emails is done via SMTP
** For Active Sync or Outlook the email backend needs to send push requests to the OX server, for details see [[OX_EMail_Push_Introduction|Email Push Introduction]]
** Several custom implementations are available on request or can be implemented by partners

*'''25''' Documents in the Files module are accessed via an API, which allows customized implementations.
** The default in large environments is to use NFS
** In small environments the local filesystem is used
** [http://www.scality.com/ Scality] is also available
** Several custom implementations are available on request or can be implemented by partners

=Social/Public Data related components, plugins and communication flow=

A subscription based plugin system allows to access data from external systems like webmail systems or social networks. The underlying concept is called SocialOX and a list of some plugins can be found here: [[SupportedCrawler]]. The integrations of messaging, contacts and calendars are done via the official API of the respective 3rd-party-service if there is one. For authentication, OAuth is used for security and privacy control if available. All plugins use HTTP(S) connections to the external services only. Access to the external email systems is done via IMAP(S) or POP3(S), depending on the service.

*'''31''' For subscription to an external calendar a plugin to subscribe to Google Calendar is available.

*'''32''' Supported external messaging services are Twitter and SMS/MMS.

*'''33''' Contacts can be imported from Xing, LinkedIn (removed since 7.10.0), MSN/Windows Live/Outlook.com, Yahoo and Google.

*'''34''' External email accounts can be integrated via POP3(S) or IMAP(S)
** There are pre-configured settings for many popular services so that users only need to enter their e-mail address and password.
** Look here how to [[install and configure the mail-account plugin]].

* '''35''' RSS feeds are loaded remotely, filtered for exploits and can be read in the UI

* '''36''' Image services like Flickr and Tumblr are integrated directly into the UI, bypassing the backend completely. Authentication is handled via OAuth.

=Publicly Available Plugins=
* An overview of the existing public plugins can be found here: [[Open-Xchange Plugin Overview]]. Many others are available on request or through partners.

Clustercheck

2017-11-08T10:04:34Z

Choeger: /* HAproxy */

= Custom clustercheck for Galera cluster =

== Introduction ==

When using [[OXLoadBalancingClustering_Database#Galera_database_setup|Galera]] as clustered MySQL database for OX App Suite, a loadbalancer is required to ''transform'' Galera's notion of ''equivalent'' cluster nodes into OX's understanding of ''master'' and ''slave'' nodes (or <code>writeUrl</code> and <code>readUrl</code>). Typical choice is a round-robin fashion for the <code>readUrl</code> and a persistent active-passive behavior for the <code>writeUrl</code>. See [[OXLoadBalancingClustering_Database#Notes_about_configuring_OX_for_use_with_Galera|the Galera setup page]] for more detailed information.

The loadbalancers need to be able to check the health status of the Galera cluster nodes in order to decide which nodes are available for read requests, and which node should be picked persistently for write requestes. The latter point is most important if we are considering a lot of ''distributed'' loadbalancers not synchronizing their target list with each other, as one of our proposed high level design options works (distributed HAproxy instances on the OX App Suite groupware nodes). It seems natural to leverage the mechanism also used by [[Maxscale|MariaDB Maxscale]] to define a ''master'' node: use the one with <code>wsrep_local_index=0</code>.

Recent versions of the packages (both MariaDB and Percona) ship with a <code>/usr/bin/clustercheck</code> script which has basically been designed for that task. However, the original version has some shortcomings, most noticeably it has been designed for and works only with HAproxy, but not with Keepalived; and it offers no support for the <code>wsrep_local_index=0</code> feature discussed above. So, we decided to improve on that script.

== Basic Installation and Testing ==

Copy-paste the script pasted below in a location on your Galera nodes where it will not be overwritten. We assume <code>/usr/local/bin/clustercheck</code> for that purpose.

The script needs a user like

GRANT PROCESS ON *.* TO 'clustercheck'@'localhost' IDENTIFIED BY '3shyShynhut';

Make the script it executable and test:

# echo "GET / HTTP/1.0" | /usr/local/bin/clustercheck clustercheck 3shyShynhut
HTTP/1.0 200 OK
Content-Length: 40

Percona XtraDB Cluster Node is synced.

Note 1: The arguments in that sample call are the MySQL user and password. We will change the way this is wired later.

Note 2: The <code>echo "GET / HTTP/1.0"</code> is actually kind of optional, but be aware that the script expects a (HTTP 1.0) request on standard input. That behavior is a change to the original <code>clustercheck</code> script, but required for Keepalived, while still being compatible to HAproxy. So you could actually test also just by using <code>echo "" | ...</code>. But you can change the behavior of the script by the URL passed, in particular by passing the URL <code>/master</code> you can test for <code>wsrep_local_index==0</code>:

# echo "GET /master HTTP/1.0" | /usr/local/bin/clustercheck clustercheck 3shyShynhut
HTTP/1.0 200 OK
Content-Length: 65

Percona XtraDB Cluster Node is synced and wsrep_local_index==0.

Or:

# echo "GET /master HTTP/1.0" | /usr/local/bin/clustercheck clustercheck 3shyShynhut
HTTP/1.0 503 Service Unavailable
Content-Length: 88

Percona XtraDB Cluster Node is not wsrep_local_index==0 and you requested master mode.

We actually recommend for security to configure some extra MySQL config file for the credentials like

# /usr/local/etc/clustercheck.my.cnf
[client]
user=clustercheck
password=3shyShynhut

Invocation then goes like

# echo "GET /master HTTP/1.0" | /usr/local/bin/clustercheck -f /usr/local/etc/clustercheck.my.cnf

For further options see the script's usage info or the source code below. We want to emphasise and recommend something like

-e /var/log/clustercheck.log

to have logging e.g. to <code>/var/log/clustercheck.log</code>. Logging is disabled by default, like in the original script.

Furthermore you want to think about and decide whether to use

-d
Consider this node as available while being donor for a SST.
Default: Donor node is considered unvailable.

-r
Consider this node as unavailable while being read-only.
Default: read-only node is considered available.

Our scripts behaves by default like the original one.

Finally master mode can not only by toggled by the request path (see above), but also by a command line parameter.

-m
Consider this as available only if it has got wsrep_local_index=0.

== Installation as web service via xinetd ==

Some of the different upstream packages install a <code>xinetd</code> service definition file <code>/etc/xinetd.d/mysqlchk</code>. If you don't have one, install the one pasted below. We use / configure it for our custom service like

<pre># default: on
# description: mysqlchk
service mysqlchk
{
# this is a config for xinetd, place it in /etc/xinetd.d/
disable = no
flags = REUSE
socket_type = stream
type = UNLISTED
port = 9200
wait = no
user = nobody
server = /usr/local/bin/clustercheck
server_args = -e /var/log/clustercheck.log -f /usr/local/etc/clustercheck.my.cnf
log_on_failure += USERID
only_from = 0.0.0.0/0

# recommended to put the IPs that need
# to connect exclusively (security purposes)
per_source = UNLIMITED
}
</pre>

You need to

touch /var/log/clustercheck.log
chown nobody /var/log/clustercheck.log

So with the usual steps (<code>apt-get install xinetd; service xinetd restart</code>, etc) we have a webservice for our clustercheck script.

'''Note''': Please ensure that you haven't set the <code>max_load</code> parameter in the xinetd configuration. This parameter will lead to <code>xinetd</code> not answering any request if the load increases above this value. So the system will be detected dead even though it actually isn't.

Final thing to do is to test this from the loadbalancer node (and adjust firewall configuration or whatever, if required).

# '''telnet db1 9200'''
Trying 10.0.0.1...
Connected to db1.
Escape character is '^]'.
'''GET / HTTP/1.0'''

HTTP/1.0 200 OK
Content-Length: 40

Percona XtraDB Cluster Node is synced.
Connection closed by foreign host.

== Loadbalancer configuration ==

=== HAproxy ===

The service can be configured for use with [[HAproxy]]. See the [[HAproxy#Configuration|configuration]] page for details.

=== Keepalived ===

The service can also be configured for use with [[Keepalived]]. See the the [[Keepalived#Keepalived_configuration_.28with_health_checks.29|Keepalived]] page for more information.

== The custom clustercheck script ==

<pre>#!/bin/bash
#
# Script to make a proxy (ie HAProxy) capable of monitoring Percona XtraDB Cluster nodes properly
#
# Authors:
# Raghavendra Prabhu <raghavendra.prabhu@percona.com>
# Olaf van Zandwijk <olaf.vanzandwijk@nedap.com>
#
# Based on the original script from Unai Rodriguez and Olaf (https://github.com/olafz/percona-clustercheck)
#
# Heavily rewritten and extended by Dominik Epple <dominik.epple@open-xchange.com> 2017-09
#
# Grant privileges required:
# GRANT PROCESS ON *.* TO 'clustercheck'@'localhost' IDENTIFIED BY '3shyShynhut';
#
# Sample usage:
# # echo "GET / HTTP/1.0" | /usr/local/bin/clustercheck clustercheck 3shyShynhut
# HTTP/1.0 200 OK
# Content-Length: 40
#
# Percona XtraDB Cluster Node is synced.
#

AVAILABLE_WHEN_DONOR=0
ERR_FILE=/dev/null
AVAILABLE_WHEN_READONLY=1
DEFAULTS_EXTRA_FILE=""
DEFAULTS_FILE=""
#Timeout exists for instances where mysqld may be hung
TIMEOUT=10
MASTER_MODE=0

usage() {
cat <<EOF
usage:
$0 [-h]
show this usage text

$0 [-e error_file] [-f defaults_file] [-F defaults_extra_file] [-t timeout_secs] [-d] [-r] [-m] [user [pass]]
Perform clustercheck. Arguments are

-e error_file
File to log errors to. Default: /dev/null

-f defaults_file
Defaults file for MySQL client. Default: none
Preferred way to pass credentials to the MySQL client.

-F defaults_extra_file
Extra defaults file for MySQL client. Default: none
Kept for compatibilty to original clustercheck.

-t timeout
Timeout for the MySQL client in seconds. Default: 10

-d
Consider this node as available while being donor for a SST. Default: Donor node is considered unvailable.

-r
Consider this node as unavailable while being read-only. Default: read-only node is considered available.

-m
Consider this as available only if it has got wsrep_local_index=0. Useful to define a "master" node. You can also toggle MASTER_MODE by using the request path "/master". Default: It is sufficient to be "Synced" for a node to be considered available.

user, pass
Credentials to connect to MySQL server to

EOF
}

log_debug() {
if [[ "$ERR_FILE" != "/dev/null" ]]; then
# the following woulde give nanoseconds timestamps, but create extra processes, which I want to avoid in normal ops
#echo "$(date --iso-8601=ns) $message" >> ${ERR_FILE}
printf "%(%FT%T%z)T" -1 >> ${ERR_FILE}
echo " $1" >> ${ERR_FILE}
fi
}

output() {
http_status=$1
message="$2"
exit_status=$3

log_debug "sending \"$http_status\" \"$message\" to the client."

length=${#message}
length=$(( length + 2 ))

echo -en "HTTP/1.0 $http_status\r\n"
echo -en "Content-Length: $length\r\n"
echo -en "\r\n"
echo -en "$message\r\n"

1<&-
exit $exit_status
}

while getopts "e:drf:t:mh" o; do
case "${o}" in
e)
ERR_FILE=${OPTARG}
;;
d)
AVAILABLE_WHEN_DONOR=1
;;
r)
AVAILABLE_WHEN_READONLY=0
;;
f)
DEFAULTS_FILE=${OPTARG}
;;
F)
DEFAULTS_EXTRA_FILE=${OPTARG}
;;
t)
TIMEOUT=${OPTARG}
;;
m)
MASTER_MODE=1
;;
h)
usage
exit 0
;;
*)
usage
exit 1
;;
esac
done
shift $((OPTIND-1))

MYSQL_USERNAME="${1}"
MYSQL_PASSWORD="${2}"

EXTRA_ARGS="--connect-timeout=$TIMEOUT -B -N"

if [[ -n "$MYSQL_USERNAME" ]]; then
EXTRA_ARGS="$EXTRA_ARGS --user=${MYSQL_USERNAME}"
fi

if [[ -n "$MYSQL_PASSWORD" ]]; then
EXTRA_ARGS="$EXTRA_ARGS --password=${MYSQL_PASSWORD}"
fi

if [[ -n "$DEFAULTS_FILE" ]]; then
if [[ -r "$DEFAULTS_FILE" ]]; then
# seems like it must be the first agrument
EXTRA_ARGS="--defaults-file=$DEFAULTS_FILE $EXTRA_ARGS "
else
echo "$0: error: defaults file $DEFAULTS_FILE not readable." >&2
exit 1
fi
fi

if [[ -n "$DEFAULTS_EXTRA_FILE" ]]; then
if [[ -r "$DEFAULTS_EXTRA_FILE" ]]; then
# seems like it must be the first agrument
EXTRA_ARGS="--defaults-extra-file=$DEFAULTS_EXTRA_FILE $EXTRA_ARGS "
else
echo "$0: error: defaults extra file $DEFAULTS_EXTRA_FILE not readable." >&2
exit 1
fi
fi

MYSQL_CMDLINE="mysql ${EXTRA_ARGS}"

# irrelevant for haproxy, required for keepalived: try to read input
log_debug "Reading HTTP request ..."
while read line
do
# https://stackoverflow.com/questions/369758/how-to-trim-whitespace-from-a-bash-variable
# remove trailing control characters
# inner expression: truncate left everything until to the right only spaces are left -> is only right spaces
# outer expression: truncate to the right the "right spaces"
line="${line%"${line##*[![:cntrl:]]}"}"

log_debug "Client sent: \"===$line===\""
if [[ -z "$line" ]]; then
log_debug "Client sent empty line, breaking"
break
fi

set -- $line
# haproxy sends by default OPTIONS, keepalived sends GET
if [[ ${1,,} = "get" || ${1,,} = "options" ]]; then
if [[ ${2:0:7} = "/master" ]]; then
log_debug "Upgrading to master mode as requrested by /master URL."
MASTER_MODE=1
fi
fi
done
log_debug "Done reading HTTP request."
set --

log_debug "Calling MySQL..."
mysql_output=$($MYSQL_CMDLINE -e 'SHOW GLOBAL STATUS WHERE Variable_name REGEXP "^(wsrep_local_state|wsrep_cluster_status|wsrep_local_index)$"; show global variables like "read_only";' 2>>${ERR_FILE} )
log_debug "MySQL output: ===$mysql_output==="

set -- $mysql_output
while [[ $# -gt 1 ]]
do
case "$1" in
wsrep_local_state|wsrep_cluster_status|wsrep_local_index|read_only)
declare $1="$2"
shift
shift
;;
*)
log_debug "unexpected output from MySQL: $1 $2"
shift
shift
;;
esac
done
log_debug "After parsing: wsrep_local_state=$wsrep_local_state wsrep_cluster_status=$wsrep_cluster_status wsrep_local_index=$wsrep_local_index read_only=$read_only"

if [[ "$wsrep_cluster_status" == 'Primary' && ( $wsrep_local_state -eq 4 || ( $wsrep_local_state -eq 2 && $AVAILABLE_WHEN_DONOR -eq 1 ) ) ]]
then
if [[ "${MASTER_MODE}" == 1 ]];then
if [[ ${wsrep_local_index} -eq 0 ]];then
output "200 OK" "Percona XtraDB Cluster Node is synced and wsrep_local_index==0." 0
else
output "503 Service Unavailable" "Percona XtraDB Cluster Node is not wsrep_local_index==0 and you requested master mode." 1
fi
fi

if [[ "${read_only}" == "ON" && $AVAILABLE_WHEN_READONLY -eq 0 ]];then
output "503 Service Unavailable" "Percona XtraDB Cluster Node is read_only and you requested AVAILABLE_WHEN_READONLY=0." 1
fi

output "200 OK" "Percona XtraDB Cluster Node is synced." 0
else
output "503 Service Unavailable" "Percona XtraDB Cluster Node is not synced or non-PRIM." 1
fi
</pre>

AppSuite:GuardCustomization

2017-08-31T07:20:20Z

Choeger: /* Emails */

= Ox Guard Customization =

== Overview ==
Guard uses several templates for emails and the Guest reader. These templates are fully customizable, and can be customized at the global level, but also at the context/user level. Changing images, colors, and layout is easy. Changing the wording is also possible, though the translation tables will then need to be updated.

== Template ID ==
Guard uses a template ID for choosing the templates to use. The template ID can be chosen for a user or context using the configuration cascade.

com.openexchange.guard.templateID=x

For any template below, a customized template can be created with the name x-templatename where x is the integer value of the template ID for the user. For example, if you wanted a custom password template based on the template "passwordtempl.html" for a context of users, you could create a template "2-passwordtempl.html" and assign the value com.openexchange.guard.templateID=2 to the context. Then, Guard will use any templates that start with "2-" for the context.

'''NOTE:'''
If no template ID is specified, or if a file specified by the template ID is not found, then the default template is used. The default is the templates with no number prefix, i.e. "passwordtempl.html"

== Templates ==
=== Emails ===
* guesttempl.html - Email template used when sending to a guest user (not an OX account)
* passwordtempl.html - Template used to send a new password to a guest user. As of 2.8, only used if newGuestsRequirePassword=true is configured
* oxpasswordtempl.html - Email template used when sending a new password to an OX user. No longer used after 2.6
* resettempl.html - Template used when sending a password reset
* guestresettempl.html - Template used when resetting guest account and password recovery is disabled

=== Guest Reader ===
* reader.html - The main guest reader template. THIS IS NOT CUSTOMIZABLE WITH TEMPLATE ID. GLOBAL CHANGES ONLY. We recommend not changing this file and using the header, footer, and style sheets for branding.
* header.html - Top header bar of the Guest reader
* footer.html - Footer of the Guest reader
* style.css - Style sheet for the Guest reader

== Email Template GetText ==
In the HTML templates, wording is surrounded by a call to gettext, which will get the translation for the user. It is used in a HTML call <$gettext("text here")>
Example:

<$gettext("You have received this email because $from has sent you a secure email message with OX Guard. You will receive a link to the secure message in a separate email.")>

== Variables ==
Some email templates have space for variables depending on their function. The variable name will begin with $ such as the above example $from.

== Guest Reader Translations ==
The Guest reader webpage uses i18next for translations. If changing the header and footer such that you need translation, use a call such as

<h2 data-i18n="PIN Required:">PIN Required:</h2>

The "data-i18n" property results in the inner HTML wording being replaced with the translation (if available for the specified language)

=====Guest Translations as of Version 2.4.2-rev8=====
Custom Guest reader translations can be managed by creating a file custom-Lang.json located in the /var/www/html/reader/l10n (on Debian 8)
This custom file should contain only the translations you want to replace in the default translation-Lang.json files.

For example, if you wanted to change the French translation of
"Welcome" from "Bienvenue" to "Bonjour", you would create a file custom-FR_fr.json with the contents

<code>
{
"Welcome" : "Bonjour"
}
</code>

The reader will load the file translations-FR_fr.json first, then it will load custom and overwrite any values found.

= Guard Product Name Customization (2.4 or 2.2.1-8+) =

== Overview ==

The Guard product name can be configured by general setting for smaller deployments, by configuration cascade, or by URL

== Product name by configuration ==

The configuration
com.openexchange.guard.productName
can be defined in the guard-core.properties (2.4) or in the guard.properties file (2.2.1-8). This product name will be passed to the UI.

This value can also be configured at the configuration cascade level

== Product name by URL ==

By editing the file yml located in /opt/open-xchange/etc/as-config.yml the property
guard.productName
can be defined based on the browser URL/IP used to address the OX backend. This product name will the be passed to the UI to be displayed by the user.