https://oxpedia.org/wiki/api.php?action=feedcontributions&user=Thomas.siedentopf&feedformat=atomOpen-Xchange - User contributions [en]2024-03-19T09:48:19ZUser contributionsMediaWiki 1.31.0https://oxpedia.org/wiki/index.php?title=AppSuite:DocumentConverter_Installation_Guide&diff=28007AppSuite:DocumentConverter Installation Guide2023-02-14T14:07:04Z<p>Thomas.siedentopf: typo</p>
<hr />
<div>= Product Description =<br />
<br />
Open-Xchange Inc. (“Open-Xchange”) has created a proprietary software program called the Open-Xchange Document Converter (the “Software”), which converts Microsoft (OOXML) and OpenOffice (ODF) office documents to PDF or to HTML5 with embedded SVG files (Scalable Vector Graphics). Additional the OX Document Converter converts PDF format files to SVG files and Microsoft files to OpenOffice files and backwards. So users can view and print documents in the existing infrastructure without any necessary additional plugins.<br />
<br />
== Introduction ==<br />
Offering document preview functionality within OX App Suite, the user expects to be able to open as much different document formats as possible or - to get a better picture - she doesn't need to take care of the document format she just received. It should just work, without knowing anything about document formats at all.<br />
<br />
To offer such transparent behavior to the user, OX App Suite needs to take care of converting a lot of document formats into the display formats needed by OX Drive. OX Drive is extended with document preview functionality by the module [[AppSuite:DocumentViewer|OX Document Viewer]]. </br><br />
DocumentConverter version 7.10.2-rev5 and higher support preview functionality in OX App Suite 7.6.3, 7.8.4 and 7.10.x. <br />
<br />
The conversion functionality is also available as stand-alone product OX Document Converter. The OX Document Converter Service allows customers the flexible integration of document conversion in their offering.<br />
<br />
The [[AppSuite:DocumentConverter_API|API reference]] describes the available actions with request parameters and results.<br />
<br />
== Requirements ==<br />
<br />
OX Document Converter requires a 64bit systems; 32bit systems are not supported.<br><br />
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.<br />
<br />
See the section about Configuration and Hardware for recommendations how to adapt settings to CPU and memory resources.<br />
<br />
== Update to 7.8.2 ==<br />
<br />
'''Note:''' For the update from earlier versions to 7.8.2 some manual adjustments are necessary. Please follow the hints described in this [[AppSuite:DocumentConverterUpdate782|article]].<br />
<br />
Details for deployments from 7.8.2 on can be found within the articles itself.<br />
<br />
== Download and Installation ==<br />
<br />
The OX Document Converter deployment consists of two functional modules, that need to be installed separately: the ''readerengine'' component and the ''Document Converter Server'' component.<br />
<br />
=== ReaderEngine ===<br />
<br />
See [[AppSuite:ReaderEngineInstall|Readerengine installation instructions]]<br />
<br />
=== Server ===<br />
<br />
See [[AppSuite:DocumentConverterInstall|Document converter installation instructions]]<br />
<br />
See [[AppSuite:DocumentConverterAPIInstall|Document converter API installation instructions]]<br />
<br />
=== Configuration ===<br />
<br />
After installation of both components ''readerengine'' and ''server'', the administrator needs to make some adjustments to the configuration.<br />
First, if this is a new installation, make sure that the node is allowing it's services to listen and be available for traffic. You can configure this by defining the "host to listen" in<br />
/opt/open-xchange/etc/overwrite.properties:<br />
com.openexchange.connector.networkListenerHost=0.0.0.0<br />
Defined here as 0.0.0.0 as a wildcard address. <br />
<br />
In order to enable users to use [[AppSuite:DocumentViewer|Preview functionality]], they must be given the appropriate permission in OX App Suite middleware properties, i.e. use '''com.openexchange.capability.document_preview=true''' in the file '''/opt/open-xchange/etc/permissions.properties''' to set this globally, or use [[ConfigCascade|ConfigCascade]].<br />
<br />
The component readerengine works with the default configuration.<br />
The settings are in the file '''documentconverter.properties'''<br />
located in the directory "/opt/open-xchange/documentconverter/etc" as described below.<br />
<br />
{{AppSuite:ReaderEngineConfig}}<br />
<br />
<br />
<!--<br />
war variant:<br />
All settings necessary for the web service to find the corresponding readerengine installation and definition of working directories and service parameters are configured within the documentconverterws.war package in the WebContent/web.xml file.<br />
<br />
{{AppSuite:ReaderEngineConfig}}<br />
<br />
--><br />
<br />
== Processing Overwiew ==<br />
In order to make use of the DocumentConverter to convert a document into an appropriate target format, the user <br />
sends HTTP(s) requests to the DocumentConverter web service. The possible requests and request parameters are specified within the [[AppSuite:DocumentConverter_API|API reference]] section.<br />
<br />
When a conversion request is received by the DocumentConverter web service, the document to be converted and specified by the URL parameter of the request is first retrieved and temporarily stored. The web service request handler in addition extracts and prepares all necessary parameters, creates a conversion job for the underlying DocumentConverter, makes the conversion call and waits for the result of the conversion to be returned. The temporary, locally stored source document gets deleted automatically before the DocumentConverter web service request returns the response. <br />
<br />
A call for document conversion is first scheduled within a queue by the DocumentConverter to be able to convert a high amount of documents in parallel, even with limited system resources and parallel conversion engines running. This is necessary since the conversion of one document might consume a lot of processing time (up to 60s by default per configured conversion engine by default).<br />
<br />
If one of the configured, parallel conversion engines gets available, it retrieves the next job from the queue and performs the conversion itself.<br />
<br />
After the conversion by one of the parallel running conversion engines of the DocumentConverter has finished, the result of the conversion is returned to the caller of the conversion request. The whole conversion process in this case is a synchronous process from the point of view of the caller.<br />
<br />
=== Conversion Job Priority ===<br />
In case of larger deployments with different document conversion demands like in the Appsuite case, it is often needed to specify some constraints wrt. the calling performance for conversion requests. <br />
E.g. in case of conversion requests as a result of direct user input within the frontend, the conversion result should be available as soon as possible for a better UI experience for the user.<br />
There are other scenarios for which there's no need for a fast conversion response, e.g. in case of a background pre conversion of documents, that are not visible for the customer at the moment of the conversion request.<br />
For such cases, the DocumentConverter provides a mechanism to set a priority at each conversion request via the 'priority' parameter.<br />
The currently available priority parameter values in increasing order are:<br />
<br />
* background<br />
* '''low'''<br />
* medium<br />
* high<br />
* instant<br />
<br />
In case no priority is set within the request, the default priority 'low' is used internally.<br />
<br />
The set priority of a conversion job affects the sorting order of the conversion queue of the DocumentConverter. Conversion jobs with a higher priority will always be processed before jobs with a lower priority. Conversion jobs with the same priority are added to the queue in a time based, sequential order according to their set priority.<br />
<br />
Due to this fact and a possible high amount of other conversion jobs with a higher priority due to e.g. direct user interaction, the caller of a conversion request should ensure to set the appropriate priority with respect to her current conversion task. In case of conversion results, intended to be seen by the user as soon as possible, setting the highest conversion priority 'instant' should be taken into account in general.<br />
<br />
== Setup And Best Practices ==<br />
<br />
The whole documentconverter product consists of 3 different parts: the OX backend documentconverter bundles, written in Java as OSGi plugins, the native readerengine and a native tool called pdf2svg.<br />
<br />
=== Readerengine ===<br />
The '''readerengine''' is - as the name implies - the low level backend engine for the converter implementation, that acts as a general purpose document conversion solution, being able to read a vast number of commonly used document formats like Microsoft binary and XML formats (MS Word, MS Excel, MS Powerpoint), the whole set of ODF (Open Document Format) document formats and many more, and to export the loaded documents into different output formats like '''PDF'''.<br />
<br />
The '''readerengine''' itself is a stripped down Open Office installation, containing some code enhancements and optimizations, provided by Open-Xchange developers. The packaging is also done in-house to have control of the whole development cycle, versioning and other aspects of the product development.<br />
<br />
=== PDF2SVG ===<br />
The '''pdf2svg''' component is a tool, that uses libpoppler for reading and processing '''PDF''' source documents and Cairo for rendering the processed '''PDF''' into '''SVG''', '''JPEG''' and '''PNG''' formats, to be finally rendered within the OX appsuite client.<br />
<br />
=== Documentconverter OSGi bundles ===<br />
The OX appsuite backend bundles of the documentconverter are responsible for receiving and processing client conversion '''requests''', to '''schedule''' conversion jobs in multi threaded queues, to manage the correct '''startup''' and '''shutdown''' of (parallel) '''readerengine''' and '''readerengine-pdf2svg''' instances, managing the '''caching''' of conversion results, '''communication''' with remote converters and remote converter caches etc.<br />
<br />
After installation of the documentconverter and related bundles, only minor changes have to be made by the admin in order to get the full functionality available within the appsuite.<br />
<br />
==== Documentconverter system packages ====<br />
The Java OSGi bundles for the documentconverter functionality are distributed via four different packages in total (revision numbers are omitted here):<br />
<br />
===== Deployments until 7.8.1 =====<br />
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by different other bundles to get access to the documentconverter OSGi service.<br />
* '''documentconverter''' This bundle contains the core documentconverter implementation as an OSGi service.<br />
* '''documentconverter-webservice''' This bundle contains the functionality to let the documentconverter offer its functionality as a webservice. In a remote scenario, this bundle needs to be installed only on those machines, that are configured to do the real conversions.<br />
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via JMX, Jolokia, Munin et al.<br />
<br />
===== Deployments from 7.8.2 on =====<br />
<br />
* '''documentconverter-api''' This bundle contains interfaces and other simple classes that are used by the documentconverter client and server bundles<br />
* '''documentconverter-client''' This bundle contains the documentconverter client implementation, running on the Ox middleware as an OSGi service.<br />
* '''documentconverter-server''' This bundle contains the documentconverter server implementation, running as a webservice on its own Ox node.<br />
* '''documentconverter-jolokia''' This optional bundle can be installed to make internal conversion statistics available for monitoring via Munin et al. The contained scripts provide access to the statistic data either via the modern '''Jolokia JMX''' bridge or the old fashioned '''showruntimestats''' functionality, provided by the OX appsuite backend. It needs to be installed on the documentconverter server side.<br />
<br />
=== General ===<br />
By taking a look at the overview of documentconverter system packages in the chapter above, it can be seen, that the two essential packages to be installed on the Ox backend (middleware) are the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter (until 7.8.1)''' / '''open-xchange-documentconverter-client (from 7.8.2 on)''' packages.<br />
<br />
If the current OX backend (middleware) node is configured to only receive client requests and to make remote conversion calls to an other node, configured as a ''real'' converter node, no additional packages need to be installed.<br />
<br />
In order to act as ''real'' converter node, the '''readerengine''' and the '''readerengine-pdf2svg''' packages need to be installed as well.<br />
<br />
'''Until 7.8.1''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the <br />
'''open-xchange-documentconverter''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.<br />
<br />
The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.<br />
<br />
In summary, the following packages must be installed in order to act as a real converter node:<br />
<br />
open-xchange-documentconverter-webservice readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database<br />
<br />
The package open-xchange-authentication-database is just needed to fulfill the dependencies.<br />
<br />
'''From 7.8.2 on''' For an OX backend node to act as a conversion webservice, the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', the '''readerengine''' and the '''readerengine-pdf2svg''' packages.<br />
<br />
The '''open-xchange-documentconverter-jolokia''' package only makes sense to be installed on an OX backend node, that acts as ''real'' converter node. It is an optional package, that is intended for monitoring purposes.<br />
<br />
In summary, the following packages must be installed in order to act as a real converter node. Package dependency management on the system ensures the installation of all depending packages:<br />
<br />
open-xchange-documentconverter-server readerengine open-xchange open-xchange-grizzly open-xchange-authentication-database<br />
<br />
The package open-xchange-authentication-database is just needed to fulfill the dependencies.<br />
<br />
=== Monitoring ===<br />
<br />
The '''open-xchange-documentconverter-jolokia''' package is an optional package, that is only useful to be installed on an OX DocumentconverterServer node, that acts as ''real'' converter node. This [[AppSuite:DocumentsMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.<br />
<br />
=== Single OX backend with documentconverter / Single converter node ===<br />
'''Deployments from 7.8.2 on:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).<br />
<br />
The simplest possible scenario is definitely a single OX appsuite backend installation with the additional installation of the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter-server''', '''readerengine''' and '''readerengine-pdf2svg''' packages.<br />
<br />
Nevertheless, this configuration can be considered as the prototype configuration block for a ''real'' converter node with different setups. Therefore, the description for this building block will contain all details, that are necessary to setup even a highly complex scenario.<br />
<br />
'''Important:''' although it is possible to run a ''real'' documentconverter on a standard OX backend node together with all other provided services, this setup is not recommended for production use, as long as each single node hardware is not sufficient enough to handle everything appropriately. This is especially true, if this node is also configured to act as a calcengine server, which itself has a resource consumption, that can be seen on the high side with a lot of memory consumption.<br />
<br />
Document conversion is a process, that might happen in the background all of the time due to permanent client requests. In such cases, the standard OX backend behavior might be slowed down in a way, that is not acceptable anymore. This is really important in cases of inferior hardware resources.<br />
<br />
So, please use this ''all-in-one'' scenario only for quick evaluation purposes, demo setups or if there's really no dedicated conversion hardware available.<br />
<br />
'''Attention:''' this deployment scenario is only supported until release-7.8.1. From release 7.8.2 on, the only available deployment scenario is a client / server scenario with two dedicated nodes acting as documentconverter client and documentconverter server (webservice).<br />
<br />
=== Configuration and Hardware ===<br />
After installation of the single documentconverter related packages, the default values for the documentconverter properties can be found in the file /opt/open-xchange/etc/documentconverter.properties. Each entry is documented and has been assigned a default value, that is in most cases sufficient for a first setup. Please take care that all listed directory paths have the appropriate write permissions for the OX backend user.<br />
<br />
'''VERY IMPORTANT:''' Each ''real'' converter node needs its own scratch and cache directories. Don't set these directories to shared directories on NFS shares etc., since file writes to the same cache/scratch directories by different backend nodes are not synchronized at the moment and will most possibly corrupt some files over the time. Actually, it is possible to use a shared network drive for the cache and scratch directories, as long as the finally used directories are unique for each given node. In this case, the documentconverter.properties file on each node has to be adjusted accordingly to guarantee such a unique, per node directory structure.<br />
<br />
In addition, you should check the following entries for their validity/sensibility:<br />
<br />
* For the scratch directory, it is recommended to use a very fast volume (e.g. on SSD or even a RAM disk, if memory allows), since temp. files are permanently created and deleted within this directory. The whole documentconverter performance will benefit from a high speed volume in any case.<br />
* The cache sizes, configured in the properties file, should be checked against the given hardware and volume sizes and adjusted accordingly, if wanted/needed. Cache entries are only read/written once during a conversion, so that the used medium does not need to be a high speed one. For the cache, it is better to use more memory than speed, since cached files will accelerate the whole conversion process the most.<br />
* The number of parallel readerengine instances used is configured via the property '''com.openexchange.documentconverter.jobProcessorCount'''. The default value of '''three''' should fit on almost all modern hardware. Please adjust this value depending on the really available CPU cores in your case. As long as the current node is configured as a conversion only node, the number of parallel processes should be in the order of (CPU core count - 1)<br />
* The '''com.openexchange.documentconverter.maxVMemMB''' config entry is the '''virtual''' memory assigned to each readerengine process. You don't need to have (jobProcessorCount * maxVMemMB) in reality, since large parts of this VMem is shared memory between all running readerengine instances. So, there's no simple formula to calculate the optimum total amount of memory. For the beginning, a '''maxVMemMB''' value of 2048 is absolutely ok and sufficient. The node, the documentconverter is running on, should have at least 8GB RAM, with more RAM and more processors being better, of course. A good recommendation would be a total amount of 16GB RAM for the node and a CPU core count of 4. A dual CPU machine with 4 cores each seems to be a better recommendation, if hardware is not a crucial point in the whole setup.<br />
* The upper limit for the '''Java VM memory''' allocation is configured in /opt/open-xchange/documentconverter/etc/process-conf.sh. A recommended value is 2048MB (-Xmx2048m). The minimum value is 512MB. This might be applicable for instances running App Suite Middleware and Documenconverter on a single machine. Please adjust this value according to available memory. But don't set this value too high, since values greater than about 4GB will have significant negative impact on the Java VM Garbage Collector. 2048MB seemed to be a very sensible value for the -Xmx limit during our tests on a dedicated documentconverter machine.<br />
<br />
=== OX backend(s) with one remote documentconverter ===<br />
A remote documentconverter setup uses (at least) one OX backend, configured as a ''real'' documentconverter as described in the chapter above. This documentconverter node should not handle standard OX backend requests, but only remote conversion requests from the standard OX backends.<br />
<br />
'''Deployments until 7.8.1:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter''' packages installed. '''readerengine''' and '''readerengine-pdf2svg''' packages are not needed on the standard OX backends.<br />
<br />
For the remote converter node, the '''open-xchange-documentconverter-webservice''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''open-xchange-documentconverter''', '''readerengine''' and '''readerengine-pdf2svg''' packages.<br />
<br />
In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.RemoteBaseUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\<br />
<br />
<blockquote><br />
com.openexchange.documentconverter.RemoteBaseUrl=http://host[:port]/documentconverterws<br />
</blockquote><br />
<br />
No other entry from the '''documentconverter.properties''' is used on the standard OX backend if the '''RemoteBaseUrl''' is set.<br />
<br />
In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.<br />
<br />
<br />
'''Deployments from 7.8.2 on:''' The standard OX backend needs to have the '''open-xchange-documentconverter-api''' and the '''open-xchange-documentconverter-client''' packages installed. readerengine and pdf2svg packages are not needed on the standard OX backends.<br />
<br />
For the remote converter node (webservice), the '''open-xchange-documentconverter-server''' package needs to be installed beside the '''open-xchange-documentconverter-api''', '''readerengine''' and '''pdf2svg''' packages.<br />
<br />
There's a properties file named '''documentconverter-client.properties''' available after installing the '''documentconverter-client''' package on the standard Ox middleware node.<br />
<br />
In order to request remote conversions, the only entry, that needs to be set within the '''documentconverter-client.properties''' file at the standard OX backend(s) is the '''com.openexchange.documentconverter.client.remoteDocumentConverterUrl''' entry. In general, this is a http-URL consisting of the remote conversion node ip address followed by the '''/documentconverterws''' path:\\<br />
<br />
<blockquote><br />
com.openexchange.documentconverter.client.remoteDocumentConverterUrl=http://host[:port]/documentconverterws<br />
</blockquote><br />
<br />
In order to check, if the remote documentconverter is correctly set up, you can enter the complete RemoteBaseUrl into a browser and should see a page, stating that the documentconverter is running.<br />
<br />
=== OX backend cluster with one remote documentconverter ===<br />
The OX backend cluster is the standard OX backend scenario, which is similar, if not equal to the standard OX backend with one documentconverter scenario above.<br />
<br />
The only thing that you need to take care of is to add the the appropriate documentconverterws ProxyPass entry to the proxy_http.conf configuration file of e.g. the Apache web server:<br />
<br />
<blockquote><br />
<Proxy /documentconverterws><br><br />
ProxyPass balancer://oxcluster/documentconverterws<br><br />
<proxy><br><br />
</blockquote><br />
<br />
=== Sample cluster installation ===<br />
<br />
A typical, basic cluster setup consists of two or more standard OX backend nodes (e.g. samplehost-node-1, samplehost-node-2, ...., samplehost-node-n), with each of these standard backend nodes having their '''com.openexchange.documentconverter.RemoteBaseUrl''' config entry set to a dedicated documentconverter cluster node (e.g. samplehost-node-x).<br />
<br />
=== OX backend cluster with two or more documentconverters ===<br />
To reduce the load on one documentconverter within a cluster installation, you can add more documentconverter nodes to the given cluster. The general setup is the same as with the '''Ox backend cluster with one remote documentconverter''' setup.<br />
<br />
<br />
In addition, care needs to be taken to add the appropriate JSESSIONID cookie handling to the cluster setup. This is done for OX clusters in general, but mentioned here for completeness. Setting the JSESSIONID cookie is essential in a multi documentconverter setup, since the Viewer client application uses stateful calls into the OX backend to retrieve the single pages of a document on demand.<br />
<br />
A typical Proxy configuration with proper stickysession handling looks as follows:<br />
<br />
<blockquote><br />
<Proxy balancer://oxcluster><br><br />
Order deny,allow<br><br />
Allow from all<br><br />
BalancerMember http://docs-develop-cluster-b1:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX1<br><br />
BalancerMember http://docs-develop-cluster-b2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=OX2<br><br />
ProxySet stickysession=JSESSIONID<br><br />
SetEnv proxy-initial-not-pooled<br><br />
SetEnv proxy-sendchunked<br><br />
</Proxy><br><br />
</blockquote><br />
<br />
'''Deployments from 7.10.1 on''' Communication between OX backend and OX Documentconverter is no longer stateful. It is not necessary to take care of session stickyness starting with 7.10.1.<br />
<br />
'''Deployments from 7.8.2 on''' Since the OX backend and the dedicated OX Documentconverter backend node are in many scenarios running on the same server, the documentconverter related node got a default port of 8008 for http communication, so that the port 8009 in the above mentioned Proxy configuration needs to be replaced by 8008 or the appropiate value from the overwrite.properties file within the documentconverter-server backend deployment. <br />
<br />
=== Remote caching with two or more documentconverters ===<br />
As mentioned above, using a cache gives a lot of performance improvements with subsequent conversion request. Having more than one ''real'' documentconverter node configured allows to get access to the remote caching feature.<br />
<br />
In general, one converter acts as a so called master cache in this scenario. It is set up as usual and as described in one of the chapters above.<br />
<br />
The second (third, ...) converter are also set up as usual, but have their '''com.openexchange.documentconverter.RemoteCacheUrls documentconverter.properties''' set, so that the first URL (of possible more URLs) points to the master cache converter.<br />
<br />
The URL to be used is the standard RemoteBaseURL with an additional '''/cache''' path set:<br />
<br />
<blockquote><br />
com.openexchange.documentconverter.RemoteCacheUrls=http://mastercachehost[:port]/documentconverterws/cache<br />
</blockquote><br />
<br />
In this case, after searching the local cache for a conversion result after a conversion request arrives without any success, all set remote cache hosts are queried for a successful cache result.<br />
<br />
If one of the remote cache hosts returns a valid cache result, the cache entry is locally replicated and the cache result is returned.<br />
<br />
If none of the remote cache hosts returns a valid cache result, a local conversion is performed, a local cache entry is created and the cache result is transferred to the first set remote cache host (the master cache host).<br />
<br />
=== Sharepoint support ===<br />
<br />
It's possible to optionally use a Sharepoint server to perform certain conversions, mainly to convert from Microsoft Word and PowerPoint to PDF so that the documents look better in the OX Document Viewer.<br />
<br />
No OX user credentials are needed on the Sharepoint server, as shown in this overview:<br />
<br />
[[File:OX_Document_Converter_Overview.jpg]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Installation_Guide_for_Debian_11.0&diff=27719AppSuite:Open-Xchange Installation Guide for Debian 11.02022-11-04T13:13:29Z<p>Thomas.siedentopf: /* JRE Installation */</p>
<hr />
<div>{{Version|7.10.6}}<br />
<br />
= OX App Suite on Debian GNU/Linux 11 =<br />
<br />
{{QuickInstIntro|release=appsuite}}<br />
<br />
= Requirements =<br />
<br />
* Plain installed Debian GNU/Linux 11, no graphical tools required<br />
* A supported Java Virtual Machine ([https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Server_Platforms learn more])<br />
* A working internet connection<br />
* 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 apt-get install vim first.<br />
<br />
= Database installation =<br />
<br />
Please consult our [[OXLoadBalancingClustering_Database#Standalone_database_setup|database installation instructions]] for information on how to install a database on the local system.<br />
<br />
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]].<br />
<br />
= JRE Installation =<br />
<br />
Debian Bullseye ships with OpenJDK 11 JRE, which is not suitable for OX App Suite. It is therefore required to install Eclipse Temurin 8 JRE with HotSpot VM. A comprehensive installation guide can be found at https://adoptium.net/de/installation/linux/#_deb_installation_on_debian_or_ubuntu. Quick instructions are:<br />
<br />
# install repo key<br />
$ wget -qO - https://packages.adoptium.net/artifactory/api/gpg/key/public | sudo apt-key add -<br />
<br />
# add repository<br />
$ cat << EOF > /etc/apt/sources.list.d/adoptopenjdk.list<br />
deb https://packages.adoptium.net/artifactory/deb/ buster main<br />
EOF<br />
<br />
= Add Open-Xchange Repository =<br />
<br />
Open-Xchange maintains public available software repositories for different platforms, such as Debian. This repository should be added to the Debian installation to enable simple installation and updates.<br />
<br />
Start a console and modify the Debian repository information file. Also add the Open-Xchange software repository:<br />
<br />
$ cat << EOF >> /etc/apt/sources.list.d/open-xchange.list<br />
<br />
deb https://software.open-xchange.com/products/appsuite/stable/appsuiteui/DebianBullseye/ /<br />
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBullseye/ / <br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianBullseye /<br />
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBullseye /<br />
EOF<br />
<br />
= Updating repositories and install packages =<br />
<br />
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]].<br />
<br />
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:<br />
<br />
$ apt-get update<br />
<br />
The following command starts the download and installation process of all required package for Open-Xchange deployment:<br />
<br />
If you want to install everything on a single server, just run<br />
<br />
$ apt-get install open-xchange open-xchange-authentication-database open-xchange-grizzly \<br />
open-xchange-admin open-xchange-appsuite \<br />
open-xchange-appsuite-backend open-xchange-appsuite-manifest<br />
<br />
'''Note 1:''' You have to choose between one of the available authentication packages depending on your requirements.<br />
Open-Xchange configuration<br />
<br />
To avoid confusion right at the start notice that Open-Xchange uses multiple administration levels and requires different credentials at some stages at the installation and server management. Note that the passwords chosen at this guide are weak and should be replaced by stronger passwords.<br />
<br />
The MySQL database user<br />
* Username: openexchange<br />
* Password used at this guide: db_password<br />
* Responsibility: Execute all kinds of database operations<br />
<br />
The Open-Xchange Admin Master<br />
* Username: oxadminmaster<br />
* Password used at this guide: admin_master_password<br />
* Responsibility: Manage contexts, manage all kinds of low level server configuration<br />
<br />
The Context Admin<br />
* Username: oxadmin<br />
* Password used at this guide: admin_password<br />
* Responsibility: Manage users/groups/resources inside a context<br />
<br />
As stated above we assume the MySQL service has been installed previously, and it is running and available.<br />
<br />
A good idea is to add the Open-Xchange binaries to PATH:<br />
<br />
$ echo PATH=$PATH:/opt/open-xchange/sbin/ >> ~/.bashrc && . ~/.bashrc<br />
<br />
Now we have to initialize the Open-Xchange configdb database. This can all be done by executing the initconfigdb script.<br />
<br />
$ /opt/open-xchange/sbin/initconfigdb --configdb-pass=db_password -a --mysql-root-passwd=root_password<br />
<br />
Use the --mysql-root-passwd option to supply the MySQL root password as configured during database installation.<br />
<br />
Add the -i option if you want to remove an already existing open-xchange configdb.<br />
<br />
'''Note:''' The -a parameter adds an openexchange account to MySQL. This account will be used for database connections from the OX App Suite middleware and requires [https://oxpedia.org/wiki/index.php?title=AppSuite:DB_user_privileges some privileges]. You can also create that account manually [https://oxpedia.org/wiki/index.php?title=OXLoadBalancingClustering_Database#Creating_Open-Xchange_user during database installation / configuration], in which case you can (should) skip the -a parameter here.<br />
<br />
Before starting any service, all basic configuration files need to be set up correctly. The --configdb-pass option indicates the password of the openexchange database user previously created, the --master-pass options specifies the password of the Open-Xchange adminmaster user that will be created when executing the oxinstaller script.<br />
<br />
'''Important:''' You should have your Open-Xchange license code at hand. If you do not plan to license Open-Xchange, you can use the option --no-license instead. Please also check [https://oxpedia.org/wiki/index.php?title=OXReportClient OXReportClient] documentation for more information about configuring a supported and maintained Open-Xchange server.<br />
<br />
'''Important:''' For MAX_MEMORY_FOR_JAVAVM a rule of thumb for simple installations is half available system memory. The value must be in MB. For example "1024" for 1GB .<br />
<br />
$ /opt/open-xchange/sbin/oxinstaller --add-license=YOUR-OX-LICENSE-CODE \<br />
--servername=oxserver --configdb-pass=db_password \<br />
--master-pass=admin_master_password --network-listener-host=localhost --servermemory MAX_MEMORY_FOR_JAVAVM<br />
<br />
'''Note:''' In a clustered setup, --network-listener-host must be set to *<br />
<br />
Now is a good time to configure the way OX will authenticate to your mail server. Edit the file /opt/open-xchange/etc/mail.properties and change the com.openexchange.mail.loginSource to use. This is very important for servers that require your full email address to log in with.<br />
<br />
# adjust com.openexchange.mail.loginSource<br />
$ vim /opt/open-xchange/etc/mail.properties<br />
<br />
After initializing the configuration, restart the Open-Xchange Administration service by executing:<br />
<br />
$ systemctl restart open-xchange<br />
<br />
Next we have to register the local server at the Open-Xchange configdb database:<br />
<br />
$ /opt/open-xchange/sbin/registerserver -n oxserver -A oxadminmaster -P admin_master_password<br />
<br />
Now we have to create a local directory that should be used as Open-Xchange filestore. This directory will contain all Infostore content and files attached to groupware objects. To maintain access by the Open-Xchange Groupware service, it is required to grant permissions to the open-xchange system user.<br />
<br />
$ mkdir /var/opt/filestore<br />
$ chown open-xchange:open-xchange /var/opt/filestore<br />
<br />
Now register the directory as a filestore at the Open-Xchange server:<br />
<br />
$ /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P admin_master_password \<br />
-t file:/var/opt/filestore -s 1000000<br />
<br />
'''Note:''' You might want to adapt the value provided with -s, the "The maximum size of the filestore in MB", see registerfilestore --help.<br />
<br />
'''Note 2:''' If you are setting up OX App Suite, you need a shared filestore accross your OX servers even though you do not plan to have the OX Files feature enabled for your customers.<br />
<br />
Finally register the groupware database, this is a separated database where all groupware specific data is stored:<br />
<br />
$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password \<br />
-n oxdatabase -p db_password -m true<br />
<br />
'''Note 3:''' Take into account that a global database is needed in order to store data across context boundaries. Please see this [https://oxpedia.org/wiki/index.php?title=AppSuite:CrossContextDatabase documentation] on how to register it.<br />
<br />
= Configure services =<br />
<br />
Now as the Open-Xchange Server has been set up and the database is running, we have to configure the Apache webserver and the mod_proxy_http module to access the groupware frontend. To gain better GUI performance, the usage of mod_expires and mod_deflate is strongly recommended. Those modules will limit the amount of client requests and compress the delivered content.<br />
<br />
$ a2enmod proxy proxy_http proxy_balancer expires deflate headers rewrite mime setenvif lbmethod_byrequests<br />
<br />
Configure the mod_proxy_http module by creating a new Apache configuration file.<br />
<br />
$ vim /etc/apache2/conf-available/proxy_http.conf<br />
<br />
<br />
<br />
<br />
<IfModule mod_proxy_http.c><br />
ProxyRequests Off<br />
ProxyStatus On<br />
# When enabled, this option will pass the Host: line from the incoming request to the proxied host.<br />
ProxyPreserveHost On<br />
# Please note that the servlet path to the soap API has changed:<br />
<Location /webservices><br />
# restrict access to the soap provisioning API<br />
Order Deny,Allow<br />
Deny from all<br />
Allow from 127.0.0.1<br />
# you might add more ip addresses / networks here<br />
# Allow from 192.168 10 172.16<br />
</Location><br />
<br />
# The old path is kept for compatibility reasons<br />
<Location /servlet/axis2/services><br />
Order Deny,Allow<br />
Deny from all<br />
Allow from 127.0.0.1<br />
</Location><br />
<br />
# Enable the balancer manager mentioned in<br />
# https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster<br />
<IfModule mod_status.c><br />
<Location /balancer-manager><br />
SetHandler balancer-manager<br />
Order Deny,Allow<br />
Deny from all<br />
Allow from 127.0.0.1<br />
</Location> <br />
</IfModule><br />
<br />
<Proxy balancer://oxcluster><br />
Order deny,allow<br />
Allow from all<br />
# multiple server setups need to have the hostname inserted instead localhost<br />
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1<br />
# Enable and maybe add additional hosts running OX here<br />
# BalancerMember http://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
# The standalone documentconverter(s) within your setup (if installed)<br />
# Make sure to restrict access to backends only<br />
# See: https://httpd.apache.org/docs/$YOUR_VERSION/mod/mod_authz_host.html#allow for more infos<br />
#<Proxy balancer://oxcluster_docs><br />
# Order Deny,Allow<br />
# Deny from all<br />
# Allow from backend1IP<br />
# BalancerMember http://converter_host:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=APP3<br />
# ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
# SetEnv proxy-initial-not-pooled<br />
# SetEnv proxy-sendchunked<br />
#</Proxy><br />
# Define another Proxy Container with different timeout for the sync clients. Microsoft recommends a minimum value of 15 minutes.<br />
# Setting the value lower than the one defined as com.openexchange.usm.eas.ping.max_heartbeat in eas.properties will lead to connection<br />
# timeouts for clients. See https://support.microsoft.com/?kbid=905013 for additional information.<br />
#<br />
# NOTE for Apache versions < 2.4:<br />
# When using a single node system or using BalancerMembers that are assigned to other balancers please add a second hostname for that<br />
# BalancerMember's IP so Apache can treat it as additional BalancerMember with a different timeout.<br />
#<br />
# Example from /etc/hosts: 127.0.0.1 localhost localhost_sync<br />
#<br />
# Alternatively select one or more hosts of your cluster to be restricted to handle only eas/usm requests<br />
<Proxy balancer://eas_oxcluster><br />
Order deny,allow<br />
Allow from all<br />
# multiple server setups need to have the hostname inserted instead localhost<br />
BalancerMember http://localhost_sync:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1<br />
# Enable and maybe add additional hosts running OX here<br />
# BalancerMember http://oxhost2:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
# When specifying additional mappings via the ProxyPass directive be aware that the first matching rule wins. Overlapping urls of<br />
# mappings have to be ordered from longest URL to shortest URL.<br />
# <br />
# Example:<br />
# ProxyPass /ajax balancer://oxcluster_with_100s_timeout/ajax<br />
# ProxyPass /ajax/test balancer://oxcluster_with_200s_timeout/ajax/test<br />
#<br />
# Requests to /ajax/test would have a timeout of 100s instead of 200s <br />
# <br />
# See:<br />
# - https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass Ordering ProxyPass Directives<br />
# - https://httpd.apache.org/docs/current/mod/mod_proxy.html#workers Worker Sharing<br />
ProxyPass /ajax balancer://oxcluster/ajax<br />
ProxyPass /appsuite/api balancer://oxcluster/ajax<br />
ProxyPass /drive balancer://oxcluster/drive<br />
ProxyPass /infostore balancer://oxcluster/infostore<br />
ProxyPass /realtime balancer://oxcluster/realtime<br />
ProxyPass /servlet balancer://oxcluster/servlet<br />
ProxyPass /webservices balancer://oxcluster/webservices<br />
<br />
#ProxyPass /documentconverterws balancer://oxcluster_docs/documentconverterws<br />
<br />
ProxyPass /usm-json balancer://eas_oxcluster/usm-json<br />
ProxyPass /Microsoft-Server-ActiveSync balancer://eas_oxcluster/Microsoft-Server-ActiveSync<br />
<br />
</IfModule><br />
<br />
<br />
Modify the default website settings to display the Open-Xchange GUI<br />
<br />
$ vim /etc/apache2/sites-enabled/000-default.conf<br />
<br />
<VirtualHost *:80><br />
ServerAdmin webmaster@localhost<br />
<br />
DocumentRoot /var/www/html<br />
<Directory /var/www/html><br />
Options -Indexes +FollowSymLinks +MultiViews<br />
AllowOverride None<br />
Order allow,deny<br />
allow from all<br />
RedirectMatch ^/$ /appsuite/<br />
</Directory><br />
<br />
<Directory /var/www/html/appsuite><br />
Options None +SymLinksIfOwnerMatch<br />
AllowOverride Indexes FileInfo<br />
</Directory><br />
</VirtualHost><br />
<br />
If you want to secure your Apache setup via HTTPS (which is highly recommended) or if you have proxies in front of your Apache please follow the instructions at:<br />
<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#.2Fopt.2Fopen-xchange.2Fetc.2Fserver.conf Grizzly configuration] in general, and specifically:<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header X-FORWARDED-PROTO Header]<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-FOR_Header X-FORWARDED-FOR Header]<br />
<br />
to properly instruct the backend about the security status of the connection and the remote IP used to contact the backend.<br />
<br />
Enable the proxy configuration<br />
<br />
$ a2enconf proxy_http.conf<br />
<br />
After the configuration is done, restart the Apache webserver<br />
<br />
$ systemctl restart apache2<br />
<br />
== Apache Setting for more concurrent Connections ==<br />
<br />
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<br />
<br />
[https://oxpedia.org/wiki/index.php?title=Tune_apache2_for_more_concurrent_connections Apache Setting for more concurrent Connections]<br />
<br />
= Creating contexts and users =<br />
<br />
Now as the whole setup is complete and you already should get a login screen when accessing the server with a webbrowser, we have to setup a context and a default user as the last step of this tutorial.<br />
<br />
The mapping defaultcontext will allow you to set this context as the default one of the entire system so that users which will be created within this context can login into Open-Xchange Server without specifying their domain at the login screen. Only one context can be specified as defaultcontext. The oxadmin user that will be created by this command is the default admin of the created context. This account will gather additional functions that are also described in the administration manual. The context id parameter must to be unique and numeric, otherwise the server will complain when you try to create a context. New contexts must be created by the oxadminmaster user, user accounts inside a context are created with the credentials of the contexts oxadmin account. The access-combination-name property defines the set of available modules and functions for users of the context.<br />
<br />
$ /opt/open-xchange/sbin/createcontext -A oxadminmaster -P admin_master_password -c 1 \<br />
-u oxadmin -d "Context Admin" -g Admin -s User -p admin_password -L defaultcontext \<br />
-e oxadmin@example.com -q 1024 --access-combination-name=groupware_standard<br />
<br />
To create a user for testing purposes (Make sure the password you use here for the user is the same password as your email account or you will not be able to use the email module until it is set right):<br />
<br />
$ /opt/open-xchange/sbin/createuser -c 1 -A oxadmin -P admin_password -u testuser \<br />
-d "Test User" -g Test -s User -p secret -e testuser@example.com \<br />
--imaplogin testuser --imapserver 127.0.0.1 --smtpserver 127.0.0.1<br />
<br />
Now connect to the server with a webbrowser and login using the credentials testuser / secret.<br />
<br />
A complete overview about the different parameter is provided at the [https://oxpedia.org/wiki/index.php?title=OX_Permission_Level permission matrix].<br />
<br />
If you need to migrate a batch of users and contexts at once, check the CSV Batch Import documentation [https://oxpedia.org/wiki/index.php?title=Csv_import page].<br />
<br />
= Log files and issue tracking =<br />
<br />
== Default logging mechanism ==<br />
<br />
Whenever unexpected or erroneous behavior takes place, it will be logged depending on the configured loglevel. All logfiles are stored at the operating systems default location. Events triggered by the Open-Xchange Groupware services are logged to a rotating file open-xchange.log.0. Those files are the very first place to monitor.<br />
<br />
$ tail -f -n200 /var/log/open-xchange/open-xchange.log.0<br />
<br />
== Alternative logging mechanisms ==<br />
<br />
Apart from the default file logging mechanism, Open-Xchange supports logging via logback framework and therefore via syslog and/or logstash. This makes it possible to directly log to a local or remote syslog daemon or other services. Logback is highly customizable, please see the documentation below.<br />
<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Logging Logback configuration Guide OX App Suite]<br />
<br />
[[Category: AppSuite]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard&diff=25762AppSuite:OX Guard2021-02-11T16:17:54Z<p>Thomas.siedentopf: /* Version Matrix */</p>
<hr />
<div>= OX Guard (Version 2.10) =<br />
<br />
For previous versions of OX Guard, please click here<br />
* [[AppSuite:OX_Guard_2-0 | Installation and information of OX Guard 2.0 - 2.2]]<br />
* [[Appsuite:OX_Guard_2_8 | Installation and information of OX Guard 2.4 - 2.8]]<br />
<br />
If upgrading from 2.6 or 2.8, please see<br />
* [[Appsuite:OX_Guard_Upgrade_2_10|Upgrading to 2.10]]<br />
<br />
== Overview ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
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:<br />
<br />
* To setup a single server installation<br />
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster<br />
* To use the database service on the existing Open-Xchange installation for Guard, no replication<br />
* To provide a basic configuration setup, no mail server configuration<br />
<br />
=== Key Features ===<br />
<br />
* Simple security at the touch of a button<br />
* Provides user based security - Separate from provider<br />
* Supplementary security to Provider based security - Layered<br />
* Powerful features yet simple to use and understand<br />
* Security - Inside and outside of the OX environment<br />
* Email and Drive integration<br />
* Uses proven PGP security<br />
<br />
=== Availability ===<br />
<br />
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.<br />
<br />
=== Requirements ===<br />
<br />
Please review [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#OX_Guard OX Guard Requirements] for a full list of requirements.<br />
<br />
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.<br />
<br />
==== Prerequisites ====<br />
<br />
* Open-Xchange REST API<br />
* Grizzly HTTP connector (open-xchange-grizzly)<br />
* A supported Java Virtual Machine (Java 8)<br />
* An Open-Xchange App Suite installation (see version Matrix)<br />
* 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.<br />
<br />
==== Version Matrix ====<br />
{|<br />
! style="text-align:left;"| Core Version<br />
! Guard Version<br />
|-<br />
|7.8.1<br />
|2.4.0 or 2.4.2<br />
|-<br />
|7.8.2<br />
|2.4.2<br />
|-<br />
|7.8.3<br />
|2.6.0<br />
|-<br />
|7.8.4<br />
|2.8.0<br />
|-<br />
|7.10.0<br />
|2.10.0<br />
|-<br />
|7.10.1<br />
|2.10.1<br />
|-<br />
|7.10.2<br />
|2.10.2<br />
|-<br />
|7.10.3<br />
|2.10.3<br />
|-<br />
|7.10.4<br />
|2.10.4<br />
|-<br />
|7.10.5<br />
|2.10.5<br />
|}<br />
<br />
=== Important Notes ===<br />
<br />
==== Customisation ====<br />
<br />
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.<br />
<br />
==== Mail Resolver ====<br />
<br />
READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!<br />
<br />
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.<br />
<br />
Once Guard is installed, please be sure to test the mail resolver using:<br />
<br />
<source lang="bash">/opt/open-xchange/sbin/guard test email@domain</source><br />
to see if the mail Resolver works.<br />
<br />
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<br />
<br />
This resolver software ''depends heavily on your local deployment''.<br />
<br />
== Download and Installation ==<br />
<br />
=== General ===<br />
<br />
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.<br />
<br />
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.<br />
<br />
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>.<br />
<br />
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).<br />
<br />
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.<br />
<br />
=== Debian Linux 9.0 (Stretch) ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange apt configuration:<br />
<br />
deb https://software.open-xchange.com/products/guard/stable/guard/DebianStretch /<br />
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /<br />
<br />
and then run for a single node installation:<br />
<br />
$ apt-get update<br />
$ 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<br />
<br />
or the following for a distributed installation:<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-guard open-xchange-guard-file-storage<br />
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).<br />
<br />
=== Debian Linux 10.0 (Buster) *Version 2.10.3+ only* ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange apt configuration:<br />
<br />
deb https://software.open-xchange.com/products/guard/stable/guard/DebianBuster /<br />
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster /<br />
<br />
and then run for a single node installation:<br />
<br />
$ apt-get update<br />
$ 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<br />
<br />
or the following for a distributed installation:<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-guard open-xchange-guard-file-storage<br />
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).<br />
<br />
=== RedHat Enterprise Linux 6 or CentOS 6 (valid until v2.10.3) ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
[open-xchange-guard-stable-guard]<br />
name=Open-Xchange-guard-stable-guard<br />
baseurl=https://software.open-xchange.com/products/guard/2.10.3/guard/RHEL6/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-backend]<br />
name=Open-Xchange-backend<br />
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and then run for a single node installation:<br />
<br />
$ yum update<br />
$ 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<br />
or the following for a distributed installation:<br />
<br />
$ yum update<br />
$ yum install open-xchange-guard open-xchange-guard-file-storage<br />
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).<br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
[open-xchange-guard-stable-guard]<br />
name=Open-Xchange-guard-stable-guard<br />
baseurl=https://software.open-xchange.com/products/guard/stable/guard/RHEL7/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-backend]<br />
name=Open-Xchange-backend<br />
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and then run for a single node installation:<br />
<br />
$ yum update<br />
$ 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<br />
or the following for a distributed installation:<br />
<br />
$ yum update<br />
$ yum install open-xchange-guard open-xchange-guard-file-storage<br />
<br />
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).<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
$ zypper ar https://software.open-xchange.com/products/guard/2.10.3/guard/SLE_12 guard-stable-guard<br />
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox-backend<br />
<br />
and then run for a single node installation:<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-file-storage open-xchange-guard-ui open-xchange-guard-ui-static<br />
<br />
or the following for a distributed installation:<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-guard open-xchange-guard-file-storage<br />
<br />
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).<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
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 &quot;Univention Configuration Registry&quot;. The variable has to contain the external FQDN of the OX Guard system:<br />
<br />
<source lang="bash">oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME</source><br />
<br />
== Update OX Guard ==<br />
<br />
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.<br />
<br />
=== Debian Linux 9.0 (Stretch) ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange apt configuration:<br />
<br />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/DebianStretch /><br />
deb <https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/DebianStretch /</source>><br />
<br />
Then run:<br />
<br />
$ apt-get update<br />
$ apt-get dist-upgrade</source><br />
<br />
If you want to see, what apt-get is going to do without actually doing it, you can run:<br />
<br />
$ apt-get dist-upgrade -s</source><br />
<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 (valid until 2.10.3) ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
[open-xchange-guard-stable-guard-updates]<br />
name=Open-Xchange-guard-stable-guard-updates<br />
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/RHEL6/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-backend]<br />
name=Open-Xchange-backend<br />
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m</source><br />
<br />
and then run:<br />
<br />
$ yum update<br />
$ yum upgrade</source><br />
<br />
=== Redhat Enterprise Linux 7 or CentOS 7 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
[open-xchange-guard-stable-guard-updates]<br />
name=Open-Xchange-guard-stable-guard-updates<br />
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/stable/guard/updates/RHEL7/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
[ox-backend]<br />
name=Open-Xchange-backend<br />
baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m</source><br />
<br />
and then run:<br />
<br />
$ yum update<br />
$ yum upgrade</source><br />
<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until 2.10.3) ===<br />
<br />
Add the package repository using <code>zypper</code> if not already present:<br />
<br />
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/guard/2.10.3/guard/updates/SLE_12 guard-stable-guard-updates<br />
$ zypper ar https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLE_12 ox-backend</source><br />
<br />
and then run:<br />
<br />
$ zypper dup -r guard-stable-guard-backend-updates<br />
$ zypper dup -r guard-stable-guard-ui-updates</source><br />
<br />
You might need to run:<br />
<br />
$ zypper ref</source><br />
<br />
to update the repository metadata before running <code>zypper</code> up.<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
<br />
== Configuration ==<br />
<br />
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 &quot;up-and-running&quot; 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.<br />
<br />
=== Basic Configuration ===<br />
<br />
<source lang="bash">$ vim /opt/open-xchange/etc/guard-core.properties</source><br />
Guard database for storing Guard user information, main lookup tables:<br />
<br />
<source lang="bash">com.openexchange.guard.oxguardDatabaseHostname=localhost</source><br />
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>:<br />
<br />
<source lang="bash">com.openexchange.guard.oxguardShardDatabase=localhost</source><br />
Username and Password for the databases above:<br />
<br />
<source lang="bash">com.openexchange.guard.databaseUsername=openexchange<br />
com.openexchange.guard.databasePassword=db_password</source><br />
Open-Xchange REST API host:<br />
<br />
<source lang="bash">com.openexchange.guard.restApiHostname=localhost</source><br />
Open-Xchange REST API username and password (need to be defined in the OX backend in the &quot;Configure services&quot; below):<br />
<br />
<source lang="bash">com.openexchange.guard.restApiUsername=apiusername<br />
com.openexchange.guard.restApiPassword=apipassword</source><br />
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients:<br />
<br />
<source lang="bash">com.openexchange.guard.externalEmailURL=URL_TO_OX</source><br />
=== Middleware Configuration on OX Guard node ===<br />
<br />
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:<br />
<br />
* <code>configdb.properties</code>: information about the existing configuration database.<br />
* <code>server.properties</code>: information about the connections have to be set.<br />
* <code>system.properties</code>: at least <code>SERVER_NAME</code> should be set.<br />
<br />
=== Sevices Configuration ===<br />
<br />
==== Apache ====<br />
<br />
Configure the <code>mod_proxy_http</code> module by adding the Guard API.<br />
<br />
Debian GNU/Linux 9.0 and 10.0<br />
<source lang="bash">$ vim /etc/apache2/sites-enabled/000-default.conf</source><br />
<br />
Redhat Enterprise Linux 6/7 or CentOS 6/7<br />
<source lang="bash">$ vim /etc/httpd/conf.d/ox.conf</source><br />
<br />
Add the following section into VirtualHost definition:<br />
<br />
<Directory /var/www/html/guard><br />
Options -Indexes<br />
</Directory><br />
<br />
Debian GNU/Linux 9.0 and 10.0<br />
<source lang="bash">$ vim /etc/apache2/conf-enabled/proxy_http.conf</source><br />
<br />
Redhat Enterprise Linux 6/7 or CentOS 6/7<br />
<source lang="bash">$ vim /etc/httpd/conf.d/proxy_http.conf</source><br />
<br />
<Proxy balancer://oxguard><br />
Order deny,allow<br />
Allow from all<br />
<br />
BalancerMember http://localhost:8009/ timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass /appsuite/api/oxguard balancer://oxguard/oxguard<br />
ProxyPass /pks balancer://oxguard/pgp<br />
ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu<br />
<br />
'''Please Note''': The Guard API settings must be inserted '''''before''''' the existing <code>ProxyPass /appsuite/api</code> parameter.<br />
<br />
'''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.<br />
<br />
After the configuration is done, restart the Apache webserver<br />
<br />
<source lang="bash">$ apachectl restart</source><br />
<br />
=== Open-Xchange Middleware Configuration ===<br />
<br />
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:<br />
<br />
<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source><br />
<source lang="bash"># OX Guard general permission, required to activate Guard in the AppSuite UI.<br />
com.openexchange.capability.guard=true<br />
<br />
# Default theme template id for all users that have no custom template id configured.<br />
com.openexchange.guard.templateID=0</source><br />
Configure the API username and password that you assigned to Guard in the <code>server.properties</code> file:<br />
<br />
<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source><br />
<source lang="bash"># Specify the user name used for HTTP basic auth by internal REST servlet<br />
com.openexchange.rest.services.basic-auth.login=apiusername<br />
<br />
# Specify the password used for HTTP basic auth by internal REST servlet<br />
com.openexchange.rest.services.basic-auth.password=apipassword</source><br />
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:<br />
<br />
<source lang="bash">$ vim /opt/open-xchange/etc/guard-api.properties</source><br />
<source lang="bash"># Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin<br />
# Default is empty<br />
com.openexchange.guard.endpoint=http://guardserver:8009/guardadmin</source><br />
Restart the OX backend<br />
<br />
<source lang="bash">$ /etc/init.d/open-xchange restart</source><br />
==== SELinux ====<br />
<br />
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:<br />
<br />
<source lang="bash">$ setsebool -P httpd_can_network_connect 1</source><br />
=== Generating the <code>oxguardpass</code> ===<br />
<br />
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'''.<br />
<br />
'''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.<br />
<br />
<source lang="bash">$ /opt/open-xchange/sbin/guard --init</source><br />
'''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.<br />
<br />
=== Test Setup ===<br />
<br />
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.<br />
<br />
To test, use an email address that exists on the OX backend (john@example.com for this example)<br />
<br />
<source lang="bash">/opt/open-xchange/sbin/guard --test john@example.com</source><br />
Guard should return information from the OX backend regarding the user associated with &quot;john@example.com&quot;. Problems resolving information for the user should be resolved before using Guard. Check Rest API passwords and settings if errors returned.<br />
<br />
=== Enabling Guard for Users ===<br />
<br />
Guard provides three capabilities for users in the environment as well as a basic &quot;core&quot; level:<br />
<br />
* Guard: <code>com.openexchange.capability.guard</code><br />
* Guard Mail: <code>com.openexchange.capability.guard-mail</code><br />
* Guard Drive: <code>com.openexchange.capability.guard-drive</code><br />
* Guard Docs: <code>com.openexchange.capability.guard-docs</code><br />
<br />
The &quot;core&quot; 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.<br />
<br />
'''Guard Mail''', '''Guard Drive''' and '''Guard Docs''' are additional options for users. &quot;Guard Mail&quot; allows users the full functionality of Guard emails. &quot;Guard Drive&quot; allows for encryption and decryption of Drive files and &quot;Guard Docs&quot; allows direct integration of Guard into Documents.<br />
<br />
Each of those three 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:<br />
<br />
==== Guard Mail: ====<br />
<br />
<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><br />
==== Guard Drive: ====<br />
<br />
<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><br />
'''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.<br />
<br />
=== External Guest recipients ===<br />
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.<br />
<code>/opt/open-xchange/etc/share.properties</code><br />
<source lang="bash">com.openexchange.share.guestCapabilityMode=static<br />
com.openexchange.share.staticGuestCapabilities=guard</source><br />
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.<br />
<source lang="bash">com.openexchange.share.transientSessions=false</source><br />
<br />
=== Guest Storage ===<br />
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.<br />
<br />
How these files are stored depend on which package, open-xchange-guard-file-storage or open-xchange-guard-s3-storage, was installed.<br />
<br />
The file retention policy is configured in the guard-core.properties file.<br />
<br />
=== Recipient key detection ===<br />
<br />
==== Local ====<br />
<br />
Guard needs to determine if an email recipients email address is an internal or external (non-ox) user.<br />
<br />
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.<br />
<br />
==== External ====<br />
<br />
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].<br />
<br />
External PGP servers to use can be configured in the guard.properties file on the Guard servers.<br />
<br />
<source lang="bash">com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371</source><br />
<br />
If you would like this Guard installation discoverable as HKP service by other Guard servers, then create an SRV record for each domain (&quot;example.com&quot; in this illustration):<br />
<br />
<source lang="bash">_hkp._tcp.example.com. 28800 IN SRV 10 1 80 appsuite.example.com.</source><br />
<br />
'''Please Note''' PGP Public key servers by default append the path /pks when the record is obtained from an SRV record. The proxy (also included in Apache config above) routes anything under /pks to the OX Guard PGP server.<br />
<source lang="bash">ProxyPass /pks balancer://oxguard/pgp</source><br />
<br />
Guard keys are also discoverable using the webkey service as specified here: https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-02<br />
This is enabled if you include the <br />
<source lang="bash">ProxyPass /.well-known/openpgpkey/hu balancer://oxguard/hu</source><br />
in the proxy_http.conf as above.<br />
Please note that the well-known request is targeted at the domain part of the mail address. Therefore clients will request for a mail address name@example.com the URI https://example.com/.well-known/openpgpkey/hu/...<br />
<br />
That means that there is the very likely need that some sort of proxying or rewriting from the webserver providing the domain needs to happen. For example for proxying using Apache 2.4 it would roughly look like this:<br />
<br />
<source lang="bash"><br />
SSLProxyEngine on<br />
<LocationMatch /.well-known/openpgpkey/><br />
ProxyPass https://ox.example.com/.well-known/openpgpkey/<br />
</LocationMatch><br />
</source><br />
<br />
=== Clustering ===<br />
<br />
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.<br />
<br />
==== MySQL ====<br />
<br />
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>:<br />
<br />
<source lang="bash">bind = 0.0.0.0</source><br />
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:<br />
<br />
<source lang="sql">GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;</source><br />
<br />
==== Apache ====<br />
<br />
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 &quot;preliminary&quot; to <code>proxy_http.conf</code>, example based on a clustered <code>mod_proxy</code>configuration:<br />
<br />
<Location /preliminary><br />
Order Deny,Allow<br />
Deny from all<br />
# Only allow access from Guard servers within the network. Do not expose this<br />
# location outside of your network. In case you use a load balancing service in front<br />
# of your Apache infrastructure you should make sure that access to /preliminary will<br />
# be blocked from the Internet / outside clients. Examples:<br />
# Allow from 192.168.0.1<br />
# Allow from 192.168.1.1 192.168.1.2<br />
# Allow from 192.168.0.<br />
</Location><br />
<br />
ProxyPass /preliminary balancer://oxcluster/preliminary<br />
<br />
<br />
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.<br />
<br />
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.<br />
<br />
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):<br />
<br />
<source lang="bash">$ apt-get install open-xchange-guard-ui-static</source><br />
<br />
==== Open-Xchange ====<br />
<br />
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:<br />
<br />
<source lang="bash">$ vim /opt/open-xchange/etc/server.properties</source><br />
and set:<br />
<br />
<source lang="bash">com.openexchange.IPCheck=false</source><br />
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):<br />
<br />
<source lang="bash">$ apt-get install open-xchange-guard-ui</source><br />
Restart the Open-Xchange service afterwards.<br />
<br />
==== OX Guard ====<br />
<br />
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.<br />
<br />
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>:<br />
<br />
<source lang="bash">com.openexchange.guard.restApiHostname=apache.example.com</source><br />
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>:<br />
<br />
<source lang="bash">com.openexchange.guard.oxBackendPort=80</source><br />
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>.<br />
<br />
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.<br />
<br />
=== Multi Node ===<br />
<br />
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].<br />
<br />
=== Mail Filter Integration (2.10.4+) ===<br />
<br />
To add additional mail filter tests (verify PGP signature, or encrypt incoming), please see<br />
[[AppSuite:OX_Guard_MailFilter | MailFilter Integration]]<br />
<br />
== Support API ==<br />
<br />
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:<br />
<br />
# Specify the username and password for accessing the Support API of Guard<br />
com.openexchange.guard.supportApiUsername=<br />
com.openexchange.guard.supportApiPassword=<br />
<br />
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. <br />
<br />
'''Warning''': Exposing the support API to the internet could be huge security risk. Only add to Apache if you know what you are doing.<br />
<br />
<br />
=== Reset password ===<br />
<br />
<code>POST /guardsupport/?action=reset_password</code><br />
<br />
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'')<br />
<br />
Parameters:<br />
<br />
* <code>email</code> – The email address of the user to reset the password for<br />
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address<br />
<br />
Response:<br />
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<br />
<br />
=== Expose key ===<br />
<br />
<code>POST /guardsupport/?action=expose_key</code><br />
<br />
Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key. Automatic resetting of exposed keys to &quot;not exposed&quot; 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'')<br />
<br />
Parameters:<br />
<br />
* <code>email</code> – The email address of the user to expose the deleted keys for<br />
* <code>cid</code> – The context id<br />
<br />
Response: A URL pointing to the downloadable exposed keys.<br />
<br />
=== Delete user ===<br />
<br />
<code>POST /guardsupport/?action=delete_user</code><br />
<br />
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'')<br />
<br />
Parameters:<br />
<br />
* <code>user_id</code> – The user's id<br />
* <code>cid</code> - The context id<br />
<br />
=== Upgrade User (Release 2.10 and later) ===<br />
<br />
<code>POST /guardsupport/?action=upgrade_guest</code><br />
<br />
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.<br />
<br />
Parameters:<br />
<br />
* <code>email</code> - The email address of the Guest user<br />
* <code>user_id</code> – The user's new id<br />
* <code>cid</code> - The user's new context id<br />
<br />
== Customisation ==<br />
<br />
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.<br />
<br />
== Entropy ==<br />
<br />
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.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=25657Caldav carddav Bundles2020-11-25T15:42:39Z<p>Thomas.siedentopf: corrected CardDAV path</p>
<hr />
<div>This article is valid until the version 7.10.2 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/latest/middleware/miscellaneous/caldav_carddav.html<br />
<br />
= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS Calendar and Address Book clients.<br />
<br />
CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDAV configuration in Mac OS X Mavericks and enter the path by hand. If you just want to enter the hostname, SSL is required. The same applies to iOS7 where SSL is always required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDAV configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:<br />
<br />
# NameVirtualHost directive no longer has any effect since Apache >=2.4<br />
# uncomment only for Apache Versions <2.4<br />
#NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for grizzly http service<br />
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass / balancer://oxserver-sync/servlet/dav/<br />
<br />
</VirtualHost><br />
<br />
If you use this method, you have to make sure that <code>dav.<MYSERVER.TLD></code> is reachable, your DNS configuration needs an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to <code>/tmp</code>.<br />
<br />
Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.<br />
<br />
$ vi <your-ox-site-configuration-file><br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Reminders [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVx5 [OR]<br />
RewriteCond %{HTTP_USER_AGENT} OpenSync [OR]<br />
RewriteCond %{HTTP_USER_AGENT} "DAVdroid" [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address\ Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalDAV%20Sync%20Adapter [OR]<br />
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} "eM Client" [OR]<br />
RewriteCond %{HTTP_USER_AGENT} "OX Sync" [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalDav [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
RewriteCond %{HTTP_USER_AGENT} "!Open-Xchange Calendar Feed Client"<br />
RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.<br />
<br />
'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule.<br />
<br />
== Autodiscovery ==<br />
<br />
By providing some DNS service name registrations for your domain and adding an additional rewrite-rule to the webserver's configuration, it's possible for some clients to automatically discover the account settings by just providing the user's e-mail address and password. The procedure is specified in [http://tools.ietf.org/html/rfc6764 RFC 6764]. <br />
<br />
The following example illustrates the DNS entries where MYSERVER.TLD would be the domain name of the ox-server, both for CalDAV and CardDAV via HTTP and HTTPS on the virtual host dav.MYSERVER.TLD:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
Additionally, a rewrite-rule similar to the following example should be added to the webserver configuration of the virtual host to enable the bootstrapping process. The rewrite target must be the root of your DAV server.<br />
The well-known aliases should be added for your DAV vhost and on the vhost serving the host matching the mail domain:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
In the case of not serving the DAV service on the vhost root additionally some DNS TXT records are recommended:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN TXT path=/servlet/dav<br />
<br />
<br />
== Installation on OX App Suite ==<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:<br />
<br />
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianStretch/ /<br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianStretch/ /<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-dav<br />
<br />
=== Debian GNU/Linux 10.0 ===<br />
<br />
Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:<br />
<br />
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster/ /<br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBuster/ /<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-dav<br />
<br />
=== SUSE Linux Enterprise Server 12 (valid until 7.10.3)===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
$ zypper ar https://software.open-xchange.com/products/appsuite/7.10.3/backend/SLE_12 ox<br />
<br />
If you have a valid maintenance subscription, please run the following command and add the ldb account data to the url so that the most recent packages get installed:<br />
<br />
$ zypper ar https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/SLES11 ox-updates<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-dav<br />
<br />
=== RedHat Enterprise Linux 6 (valid until 7.10.3)===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# [ox-updates]<br />
# name=Open-Xchange Updates<br />
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/<br />
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
# enabled=1<br />
# gpgcheck=1<br />
# metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-dav<br />
<br />
===RedHat Enterprise Linux 7 ===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# [ox-updates]<br />
# name=Open-Xchange Updates<br />
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/<br />
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
# enabled=1<br />
# gpgcheck=1<br />
# metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-dav<br />
<br />
===CentOS 6 (valid until 7.10.3)===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=https://software.open-xchange.com/products/appsuite/7.10.3/backend/RHEL6/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# [ox-updates]<br />
# name=Open-Xchange Updates<br />
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/7.10.3/backend/updates/RHEL6/<br />
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
# enabled=1<br />
# gpgcheck=1<br />
# metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-dav<br />
<br />
===CentOS 7===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=https://software.open-xchange.com/products/appsuite/stable/backend/RHEL7/<br />
gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# [ox-updates]<br />
# name=Open-Xchange Updates<br />
# baseurl=https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/RHEL7/<br />
# gpgkey=https://software.open-xchange.com/oxbuildkey.pub<br />
# enabled=1<br />
# gpgcheck=1<br />
# metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-dav<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:<br />
<br />
===com.openexchange.caldav.enabled===<br />
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
This means: In general CalDAV is turned off, but using the <code>contextSets</code> feature of the config cascade it is turned on for everyone that has infostore access.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years". <br />
<br />
===com.openexchange.caldav.url===<br />
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:<br />
<br />
/opt/open-xchange/etc/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX_EMail_Push_Introduction&diff=25320OX EMail Push Introduction2020-05-08T11:58:17Z<p>Thomas.siedentopf: </p>
<hr />
<div>= Introduction to EMail Push in Open-Xchange =<br />
<br />
== Abstract ==<br />
<br />
In combination with [[OXtender_for_Business_Mobility]] (EAS), the [[AppSuite:OX_Mail_v2_0 | Mail App]] and [[AppSuite:PushToUI | websockets based push]] to the webinterface a working mail push is very<br />
important. It is important to know, that this is a combined<br />
requirement to the mail server and the Open-Xchange server to make<br />
that happen.<br />
<br />
The listed OXtenders are accessing Open-Xchange via the USM<br />
interface (Universal Synchronization Module, which is the package<br />
open-xchange-usm).<br />
<br />
In summary:<br />
<br />
* '''EAS uses an internal mail poll if no push available'''<br />
<br />
== Mail Push with [[OXtender_for_Business_Mobility]] ==<br />
<br />
In addition to an externally triggered mail push, in internal mail<br />
poll initiated by the usm module is executed.<br />
<br />
This is, how this polling can be influenced via<br />
<tt>/opt/open-xchange/etc/groupware/usm.properties</tt>:<br />
<br />
# <tt>com.openexchange.usm.session.sync.email_pull_delay=50%</tt><br />
# <tt>com.openexchange.usm.session.sync.email_pull_min_delay=60000</tt><br />
<br />
<br />
These values are the default values.<br />
<br />
1. defines, when an internal poll should be triggered while waiting<br />
for the client. This can be done as an absolute value (in<br />
milliseconds) or as a percentage value based on the waiting time as<br />
been specified by by the client per Active Sync Protocol (EAS). In the<br />
EAS protocol, the client specifies this time dynamically, usually<br />
between 30 seconds and 30 minutes. If an absolute time is specified<br />
here and the time set by the client is smaller, a mail poll is<br />
initiated at the end of the waiting time if not prevented by the<br />
setting of 2.<br />
<br />
<br />
2. defines an additional minimum waiting time, which is enforced to be<br />
followed, before an internal poll is executed. Is the value as<br />
specified by the EAS client/protocol smaller than this value, no poll<br />
will be executed. If 2. is set to a negative value, the internal mail<br />
polling of USM will be completely disabled.<br />
<br />
<br />
=== Examples ===<br />
<br />
==== A ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=50%<br />
com.openexchange.usm.session.sync.email_pull_min_delay=-1<br />
<br />
Internal mail poll is disabled.<br />
<br />
==== B ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=50%<br />
com.openexchange.usm.session.sync.email_pull_min_delay=60000<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
!Client waiting time<br />
!Mail polling interval<br />
|-<br />
|30 seconds<br />
|no polling<br />
|-<br />
|90 seconds<br />
|poll after 60 seconds (!)<br />
|-<br />
|180 seconds<br />
|poll after 90 seconds<br />
|-<br />
|1800 seconds<br />
|poll after 900 seconds<br />
|}<br />
<br />
==== C ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=120000<br />
com.openexchange.usm.session.sync.email_pull_min_delay=60000<br />
<br />
{| class="wikitable"<br />
|-<br />
!Client waiting time<br />
!Mail polling interval<br />
|-<br />
|30 seconds<br />
|no polling<br />
|-<br />
|90 seconds<br />
|poll after 90 seconds (!)<br />
|-<br />
|180 seconds<br />
|poll after 120 seconds<br />
|-<br />
|1800 seconds<br />
|poll after 120 seconds<br />
|}<br />
<br />
<br />
==== D ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=60000<br />
com.openexchange.usm.session.sync.email_pull_min_delay=120000<br />
<br />
{| class="wikitable"<br />
|-<br />
!Client waiting time<br />
!Mail polling interval<br />
|-<br />
|30 seconds<br />
|no polling<br />
|-<br />
|90 seconds<br />
|no polling (!)<br />
|-<br />
|180 seconds<br />
|poll after 120 seconds<br />
|-<br />
|1800 seconds<br />
|poll after 120 seconds<br />
|}<br />
<br />
<br />
This example is not usefull, it should show, that property 2. has a<br />
higher priority than property 1.<br />
<br />
<br />
The default behaviour can be described like shown below:<br />
<br />
client waiting time X (EAS Ping):<br />
X < 60 s -> no internal mail poll<br />
60 s <= X <= 120 s -> internal poll after 60 s<br />
120 s < X -> internal poll after X/2 s<br />
<br />
== Open-Xchange Mail Push implementations ==<br />
<br />
There are currently the following available implementations of mail push.<br />
<br />
=== The [https://documentation.open-xchange.com/latest/middleware/mail/dovecot/dovecot_push.html Dovecot_Mailpush] ===<br />
<br />
Is the recommended push mechanism in an Open-Xchange / Dovecot setup supporting also permanent push registrations for [[AppSuite:OX_Mail_v2_0 | OX Mail App]] and [[AppSuite:PushToUI | websockets]].<br />
<br />
=== The [[MailNotify_Bundle]] ===<br />
<br />
This package only integrates with cyrus-imapd using its notification protocol.<br />
<br />
=== The MALPoll Bundle ===<br />
<br />
The package '''open-xchange-push-malpoll''' simulates mail push in polling the IMAP server on a regular<br />
basis. This can only be recommended on small installations as it might stress the IMAP server.<br />
<br />
=== The [[MailPushIMAPIDLE Bundle]] ===<br />
<br />
Mail push via IMAP IDLE.<br />
Works with all IMAP servers being able to do IMAP IDLE. Too many IMAP IDLE sessions can hurt huge installations as well as Open-Xchange due to number of open sessions and connections. Please use with care.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Installation_Guide_for_Debian_10.0&diff=25316AppSuite:Open-Xchange Installation Guide for Debian 10.02020-04-28T05:29:57Z<p>Thomas.siedentopf: </p>
<hr />
<div>{{Version|7.10.3}}<br />
<br />
= OX App Suite on Debian GNU/Linux 10 =<br />
<br />
{{QuickInstIntro|release=appsuite}}<br />
<br />
= Requirements =<br />
<br />
* Plain installed Debian GNU/Linux 10, no graphical tools required<br />
* A supported Java Virtual Machine ([https://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Server_Platforms learn more])<br />
* A working internet connection<br />
* 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 apt-get install vim first.<br />
<br />
= Database installation =<br />
<br />
Please consult our [[OXLoadBalancingClustering_Database#Standalone_database_setup|database installation instructions]] for information on how to install a database on the local system.<br />
<br />
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]].<br />
<br />
= JRE Installation =<br />
<br />
Debian Buster ships with OpenJDK 11 JRE, which is not suitable for OX App Suite. It is therefore required to install AdoptOpenJDK 8 JRE with HotSpot VM. A comprehensive installation guide can be found at https://adoptopenjdk.net/installation.html#linux-pkg. Quick instructions are:<br />
<br />
# install repo key<br />
$ wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | sudo apt-key add -<br />
<br />
# add repository<br />
$ cat << EOF > /etc/apt/sources.list.d/adoptopenjdk.list<br />
deb https://adoptopenjdk.jfrog.io/adoptopenjdk/deb/ buster main<br />
EOF<br />
<br />
The correct JRE package is adoptopenjdk-8-hotspot-jre. It doesn't need to be installed manually as it is resolved and installed automatically by the debian package manager as a dependency of the open-xchange packages.<br />
<br />
= Add Open-Xchange Repository =<br />
<br />
Open-Xchange maintains public available software repositories for different platforms, such as Debian. This repository should be added to the Debian installation to enable simple installation and updates.<br />
<br />
Start a console and modify the Debian repository information file. Also add the Open-Xchange software repository:<br />
<br />
$ cat << EOF >> /etc/apt/sources.list.d/open-xchange.list<br />
<br />
deb https://software.open-xchange.com/products/appsuite/stable/appsuiteui/DebianBuster/ /<br />
deb https://software.open-xchange.com/products/appsuite/stable/backend/DebianBuster/ /<br />
<br />
# if you have a valid maintenance subscription, please uncomment the <br />
# following and add the ldb account data to the url so that the most recent<br />
# packages get installed<br />
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/appsuiteui/updates/DebianBuster /<br />
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/appsuite/stable/backend/updates/DebianBuster /<br />
EOF<br />
<br />
= Updating repositories and install packages =<br />
<br />
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]].<br />
<br />
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:<br />
<br />
$ apt-get update<br />
<br />
The following command starts the download and installation process of all required package for Open-Xchange deployment:<br />
<br />
If you want to install everything on a single server, just run<br />
<br />
$ apt-get install open-xchange open-xchange-authentication-database open-xchange-grizzly \<br />
open-xchange-admin open-xchange-appsuite \<br />
open-xchange-appsuite-backend open-xchange-appsuite-manifest<br />
<br />
'''Note 1:''' You have to choose between one of the available authentication packages depending on your requirements.<br />
Open-Xchange configuration<br />
<br />
To avoid confusion right at the start notice that Open-Xchange uses multiple administration levels and requires different credentials at some stages at the installation and server management. Note that the passwords chosen at this guide are weak and should be replaced by stronger passwords.<br />
<br />
The MySQL database user<br />
* Username: openexchange<br />
* Password used at this guide: db_password<br />
* Responsibility: Execute all kinds of database operations<br />
<br />
The Open-Xchange Admin Master<br />
* Username: oxadminmaster<br />
* Password used at this guide: admin_master_password<br />
* Responsibility: Manage contexts, manage all kinds of low level server configuration<br />
<br />
The Context Admin<br />
* Username: oxadmin<br />
* Password used at this guide: admin_password<br />
* Responsibility: Manage users/groups/resources inside a context<br />
<br />
As stated above we assume the MySQL service has been installed previously, and it is running and available.<br />
<br />
A good idea is to add the Open-Xchange binaries to PATH:<br />
<br />
$ echo PATH=$PATH:/opt/open-xchange/sbin/ >> ~/.bashrc && . ~/.bashrc<br />
<br />
Now we have to initialize the Open-Xchange configdb database. This can all be done by executing the initconfigdb script.<br />
<br />
$ /opt/open-xchange/sbin/initconfigdb --configdb-pass=db_password -a --mysql-root-passwd=root_password<br />
<br />
Use the --mysql-root-passwd option to supply the MySQL root password as configured during database installation.<br />
<br />
Add the -i option if you want to remove an already existing open-xchange configdb.<br />
<br />
'''Note:''' The -a parameter adds an openexchange account to MySQL. This account will be used for database connections from the OX App Suite middleware and requires [https://oxpedia.org/wiki/index.php?title=AppSuite:DB_user_privileges some privileges]. You can also create that account manually [https://oxpedia.org/wiki/index.php?title=OXLoadBalancingClustering_Database#Creating_Open-Xchange_user during database installation / configuration], in which case you can (should) skip the -a parameter here.<br />
<br />
Before starting any service, all basic configuration files need to be set up correctly. The --configdb-pass option indicates the password of the openexchange database user previously created, the --master-pass options specifies the password of the Open-Xchange adminmaster user that will be created when executing the oxinstaller script.<br />
<br />
'''Important:''' You should have your Open-Xchange license code at hand. If you do not plan to license Open-Xchange, you can use the option --no-license instead. Please also check [https://oxpedia.org/wiki/index.php?title=OXReportClient OXReportClient] documentation for more information about configuring a supported and maintained Open-Xchange server.<br />
<br />
'''Important:''' For MAX_MEMORY_FOR_JAVAVM a rule of thumb for simple installations is half available system memory. The value must be in MB. For example "1024" for 1GB .<br />
<br />
$ /opt/open-xchange/sbin/oxinstaller --add-license=YOUR-OX-LICENSE-CODE \<br />
--servername=oxserver --configdb-pass=db_password \<br />
--master-pass=admin_master_password --network-listener-host=localhost --servermemory MAX_MEMORY_FOR_JAVAVM<br />
<br />
'''Note:''' In a clustered setup, --network-listener-host must be set to *<br />
<br />
Now is a good time to configure the way OX will authenticate to your mail server. Edit the file /opt/open-xchange/etc/mail.properties and change the com.openexchange.mail.loginSource to use. This is very important for servers that require your full email address to log in with.<br />
<br />
# adjust com.openexchange.mail.loginSource<br />
$ vim /opt/open-xchange/etc/mail.properties<br />
<br />
After initializing the configuration, restart the Open-Xchange Administration service by executing:<br />
<br />
$ systemctl restart open-xchange<br />
<br />
Next we have to register the local server at the Open-Xchange configdb database:<br />
<br />
$ /opt/open-xchange/sbin/registerserver -n oxserver -A oxadminmaster -P admin_master_password<br />
<br />
Now we have to create a local directory that should be used as Open-Xchange filestore. This directory will contain all Infostore content and files attached to groupware objects. To maintain access by the Open-Xchange Groupware service, it is required to grant permissions to the open-xchange system user.<br />
<br />
$ mkdir /var/opt/filestore<br />
$ chown open-xchange:open-xchange /var/opt/filestore<br />
<br />
Now register the directory as a filestore at the Open-Xchange server:<br />
<br />
$ /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P admin_master_password \<br />
-t file:/var/opt/filestore -s 1000000<br />
<br />
'''Note:''' You might want to adapt the value provided with -s, the "The maximum size of the filestore in MB", see registerfilestore --help.<br />
<br />
'''Note 2:''' If you are setting up OX App Suite, you need a shared filestore accross your OX servers even though you do not plan to have the OX Files feature enabled for your customers.<br />
<br />
Finally register the groupware database, this is a separated database where all groupware specific data is stored:<br />
<br />
$ /opt/open-xchange/sbin/registerdatabase -A oxadminmaster -P admin_master_password \<br />
-n oxdatabase -p db_password -m true<br />
<br />
'''Note 3:''' Take into account that a global database is needed in order to store data across context boundaries. Please see this [https://oxpedia.org/wiki/index.php?title=AppSuite:CrossContextDatabase documentation] on how to register it.<br />
<br />
= Configure services =<br />
<br />
Now as the Open-Xchange Server has been set up and the database is running, we have to configure the Apache webserver and the mod_proxy_http module to access the groupware frontend. To gain better GUI performance, the usage of mod_expires and mod_deflate is strongly recommended. Those modules will limit the amount of client requests and compress the delivered content.<br />
<br />
$ a2enmod proxy proxy_http proxy_balancer expires deflate headers rewrite mime setenvif lbmethod_byrequests<br />
<br />
Configure the mod_proxy_http module by creating a new Apache configuration file.<br />
<br />
$ vim /etc/apache2/conf-available/proxy_http.conf<br />
<br />
<br />
<br />
<IfModule mod_proxy_http.c><br />
ProxyRequests Off<br />
ProxyStatus On<br />
# When enabled, this option will pass the Host: line from the incoming request to the proxied host.<br />
ProxyPreserveHost On<br />
# Please note that the servlet path to the soap API has changed:<br />
<Location /webservices><br />
# restrict access to the soap provisioning API<br />
Order Deny,Allow<br />
Deny from all<br />
Allow from 127.0.0.1<br />
# you might add more ip addresses / networks here<br />
# Allow from 192.168 10 172.16<br />
</Location><br />
<br />
# The old path is kept for compatibility reasons<br />
<Location /servlet/axis2/services><br />
Order Deny,Allow<br />
Deny from all<br />
Allow from 127.0.0.1<br />
</Location><br />
<br />
# Enable the balancer manager mentioned in<br />
# https://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster<br />
<IfModule mod_status.c><br />
<Location /balancer-manager><br />
SetHandler balancer-manager<br />
Order Deny,Allow<br />
Deny from all<br />
Allow from 127.0.0.1<br />
</Location> <br />
</IfModule><br />
<br />
<Proxy balancer://oxcluster><br />
Order deny,allow<br />
Allow from all<br />
# multiple server setups need to have the hostname inserted instead localhost<br />
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1<br />
# Enable and maybe add additional hosts running OX here<br />
# BalancerMember http://oxhost2:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
# The standalone documentconverter(s) within your setup (if installed)<br />
# Make sure to restrict access to backends only<br />
# See: https://httpd.apache.org/docs/$YOUR_VERSION/mod/mod_authz_host.html#allow for more infos<br />
#<Proxy balancer://oxcluster_docs><br />
# Order Deny,Allow<br />
# Deny from all<br />
# Allow from backend1IP<br />
# BalancerMember http://converter_host:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 keepalive=On route=APP3<br />
# ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
# SetEnv proxy-initial-not-pooled<br />
# SetEnv proxy-sendchunked<br />
#</Proxy><br />
# Define another Proxy Container with different timeout for the sync clients. Microsoft recommends a minimum value of 15 minutes.<br />
# Setting the value lower than the one defined as com.openexchange.usm.eas.ping.max_heartbeat in eas.properties will lead to connection<br />
# timeouts for clients. See https://support.microsoft.com/?kbid=905013 for additional information.<br />
#<br />
# NOTE for Apache versions < 2.4:<br />
# When using a single node system or using BalancerMembers that are assigned to other balancers please add a second hostname for that<br />
# BalancerMember's IP so Apache can treat it as additional BalancerMember with a different timeout.<br />
#<br />
# Example from /etc/hosts: 127.0.0.1 localhost localhost_sync<br />
#<br />
# Alternatively select one or more hosts of your cluster to be restricted to handle only eas/usm requests<br />
<Proxy balancer://eas_oxcluster><br />
Order deny,allow<br />
Allow from all<br />
# multiple server setups need to have the hostname inserted instead localhost<br />
BalancerMember http://localhost_sync:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP1<br />
# Enable and maybe add additional hosts running OX here<br />
# BalancerMember http://oxhost2:8009 timeout=1900 smax=0 ttl=60 retry=60 loadfactor=50 route=APP2<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=On<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
# When specifying additional mappings via the ProxyPass directive be aware that the first matching rule wins. Overlapping urls of<br />
# mappings have to be ordered from longest URL to shortest URL.<br />
# <br />
# Example:<br />
# ProxyPass /ajax balancer://oxcluster_with_100s_timeout/ajax<br />
# ProxyPass /ajax/test balancer://oxcluster_with_200s_timeout/ajax/test<br />
#<br />
# Requests to /ajax/test would have a timeout of 100s instead of 200s <br />
# <br />
# See:<br />
# - https://httpd.apache.org/docs/current/mod/mod_proxy.html#proxypass Ordering ProxyPass Directives<br />
# - https://httpd.apache.org/docs/current/mod/mod_proxy.html#workers Worker Sharing<br />
ProxyPass /ajax balancer://oxcluster/ajax<br />
ProxyPass /appsuite/api balancer://oxcluster/ajax<br />
ProxyPass /drive balancer://oxcluster/drive<br />
ProxyPass /infostore balancer://oxcluster/infostore<br />
ProxyPass /realtime balancer://oxcluster/realtime<br />
ProxyPass /servlet balancer://oxcluster/servlet<br />
ProxyPass /webservices balancer://oxcluster/webservices<br />
<br />
#ProxyPass /documentconverterws balancer://oxcluster_docs/documentconverterws<br />
<br />
ProxyPass /usm-json balancer://eas_oxcluster/usm-json<br />
ProxyPass /Microsoft-Server-ActiveSync balancer://eas_oxcluster/Microsoft-Server-ActiveSync<br />
<br />
</IfModule><br />
<br />
<br />
Modify the default website settings to display the Open-Xchange GUI<br />
<br />
$ vim /etc/apache2/sites-enabled/000-default.conf<br />
<br />
<VirtualHost *:80><br />
ServerAdmin webmaster@localhost<br />
<br />
DocumentRoot /var/www/html<br />
<Directory /var/www/html><br />
Options -Indexes +FollowSymLinks +MultiViews<br />
AllowOverride None<br />
Order allow,deny<br />
allow from all<br />
RedirectMatch ^/$ /appsuite/<br />
</Directory><br />
<br />
<Directory /var/www/html/appsuite><br />
Options None +SymLinksIfOwnerMatch<br />
AllowOverride Indexes FileInfo<br />
</Directory><br />
</VirtualHost><br />
<br />
If you want to secure your Apache setup via HTTPS (which is highly recommended) or if you have proxies in front of your Apache please follow the instructions at:<br />
<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#.2Fopt.2Fopen-xchange.2Fetc.2Fserver.conf Grizzly configuration] in general, and specifically:<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-PROTO_Header X-FORWARDED-PROTO Header]<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly#X-FORWARDED-FOR_Header X-FORWARDED-FOR Header]<br />
<br />
to properly instruct the backend about the security status of the connection and the remote IP used to contact the backend.<br />
<br />
Enable the proxy configuration<br />
<br />
$ a2enconf proxy_http.conf<br />
<br />
After the configuration is done, restart the Apache webserver<br />
<br />
$ systemctl restart apache2<br />
<br />
== Apache Setting for more concurrent Connections ==<br />
<br />
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<br />
<br />
[https://oxpedia.org/wiki/index.php?title=Tune_apache2_for_more_concurrent_connections Apache Setting for more concurrent Connections]<br />
<br />
= Creating contexts and users =<br />
<br />
Now as the whole setup is complete and you already should get a login screen when accessing the server with a webbrowser, we have to setup a context and a default user as the last step of this tutorial.<br />
<br />
The mapping defaultcontext will allow you to set this context as the default one of the entire system so that users which will be created within this context can login into Open-Xchange Server without specifying their domain at the login screen. Only one context can be specified as defaultcontext. The oxadmin user that will be created by this command is the default admin of the created context. This account will gather additional functions that are also described in the administration manual. The context id parameter must to be unique and numeric, otherwise the server will complain when you try to create a context. New contexts must be created by the oxadminmaster user, user accounts inside a context are created with the credentials of the contexts oxadmin account. The access-combination-name property defines the set of available modules and functions for users of the context.<br />
<br />
$ /opt/open-xchange/sbin/createcontext -A oxadminmaster -P admin_master_password -c 1 \<br />
-u oxadmin -d "Context Admin" -g Admin -s User -p admin_password -L defaultcontext \<br />
-e oxadmin@example.com -q 1024 --access-combination-name=groupware_standard<br />
<br />
To create a user for testing purposes (Make sure the password you use here for the user is the same password as your email account or you will not be able to use the email module until it is set right):<br />
<br />
$ /opt/open-xchange/sbin/createuser -c 1 -A oxadmin -P admin_password -u testuser \<br />
-d "Test User" -g Test -s User -p secret -e testuser@example.com \<br />
--imaplogin testuser --imapserver 127.0.0.1 --smtpserver 127.0.0.1<br />
<br />
Now connect to the server with a webbrowser and login using the credentials testuser / secret.<br />
<br />
A complete overview about the different parameter is provided at the [https://oxpedia.org/wiki/index.php?title=OX_Permission_Level permission matrix].<br />
<br />
If you need to migrate a batch of users and contexts at once, check the CSV Batch Import documentation [https://oxpedia.org/wiki/index.php?title=Csv_import page].<br />
<br />
= Log files and issue tracking =<br />
<br />
== Default logging mechanism ==<br />
<br />
Whenever unexpected or erroneous behavior takes place, it will be logged depending on the configured loglevel. All logfiles are stored at the operating systems default location. Events triggered by the Open-Xchange Groupware services are logged to a rotating file open-xchange.log.0. Those files are the very first place to monitor.<br />
<br />
$ tail -f -n200 /var/log/open-xchange/open-xchange.log.0<br />
<br />
== Alternative logging mechanisms ==<br />
<br />
Apart from the default file logging mechanism, Open-Xchange supports logging via logback framework and therefore via syslog and/or logstash. This makes it possible to directly log to a local or remote syslog daemon or other services. Logback is highly customizable, please see the documentation below.<br />
<br />
* [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Logging Logback configuration Guide OX App Suite]<br />
<br />
[[Category: AppSuite]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=21497OXReportClient2016-02-19T10:25:51Z<p>Thomas.siedentopf: /* Explanation of the appsuite report console output */</p>
<hr />
<div>== Introduction ==<br />
<br />
* For customers who are using '''OX App Suite''' please [http://oxpedia.org/wiki/index.php?title=AppSuite:OXReportClient click here]<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Report kinds ===<br />
<br />
In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination. <br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of the appsuite report console output ===<br />
<br />
<pre><br />
$ /opt/open-xchange/sbin/report -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %) <br />
UUID: f5f511d663ff462f8f963dfa41bd8cd2<br />
Type: default<br />
Total time: 389 milliseconds<br />
Avg. time per context: 77 milliseconds<br />
Report was finished: Wed Jul 08 13:42:25 CEST 2015<br />
<br />
------ report -------<br />
{<br />
"macdetail" : {<br />
"capabilitySets" : [ {<br />
"total" : 2,<br />
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 0,<br />
"disabled" : 0<br />
}, {<br />
"total" : 11,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 3,<br />
"disabled" : 0<br />
}, {<br />
"total" : 6,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 2,<br />
"disabled" : 0<br />
} ]<br />
},<br />
"total" : {<br />
"guests" : 22,<br />
"links" : 10,<br />
"contexts" : 5,<br />
"users" : 19,<br />
"report-format" : "appsuite-short"<br />
},<br />
"clientlogincountyear" : {<br />
"appsuite" : "7",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "9",<br />
"carddav" : "1"<br />
},<br />
"clientlogincount" : {<br />
"appsuite" : "4",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "2",<br />
"carddav" : "1"<br />
},<br />
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",<br />
"reportType" : "default",<br />
"timestamps" : {<br />
"start" : 1436355744714,<br />
"stop" : 1436355745103<br />
},<br />
"version" : {<br />
"version" : "7.8.0-Rev0",<br />
"buildDate" : "develop"<br />
},<br />
"configs" : {<br />
"com.openexchange.mail.adminMailLoginEnabled" : "true"<br />
}<br />
}<br />
------ end -------<br />
</pre><br />
<br />
'''macdetail:'''<br />
: detailed information about existing module access combinations and its usage <br />
'''total:'''<br />
: accumulated user, guest, link (anonymous share) and context count<br />
'''clientlogincountyear:'''<br />
: number of client logins for the last year (1 year back from current date)<br />
'''clientlogincount:'''<br />
: number of client logins for the last month<br />
'''uuid:'''<br />
: a unique id for the report<br />
'''reportType:'''<br />
: given name for that report (normally 'default')<br />
'''timestamps:'''<br />
: timestamps of the start and end time of the report<br />
'''versions:'''<br />
: version and build date of the server<br />
'''configs:'''<br />
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')<br />
<br />
=== Explanation of the old console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -o -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users guests links'''<br />
5 19 22 10 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''key value'''<br />
com.openexchange.mail.adminMailLoginEnabled true <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''guests:'''<br />
:total number of guests<br />
'''linkss:'''<br />
:total number of links shared to anonymous users<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
'''key:'''<br />
:key of the configuration property<br />
'''value:'''<br />
:value of the configuration property<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id, capability sets<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)<br />
<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=21320Caldav carddav Bundles2016-01-15T07:09:58Z<p>Thomas.siedentopf: /* Alternative 1: Apache vhost (recommended) */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS Calendar and Address Book clients.<br />
<br />
CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDAV configuration in Mac OS X Mavericks and enter the path by hand. If you just want to enter the hostname, SSL is required. The same applies to iOS7 where SSL is always required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDAV configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:<br />
<br />
# NameVirtualHost directive no longer has any effect since Apache >=2.4<br />
# uncomment only for Apache Versions <2.4<br />
#NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for grizzly http service<br />
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass / balancer://oxserver-sync/servlet/dav/<br />
<br />
</VirtualHost><br />
<br />
If you use this method, you have to make sure that <code>dav.<MYSERVER.TLD></code> is reachable, your DNS configuration needs an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to <code>/tmp</code>.<br />
<br />
Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.<br />
<br />
$ vi <your-ox-site-configuration-file><br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Reminders [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address\ Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]<br />
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} eM\ Client [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.<br />
<br />
'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule .<br />
<br />
== Autodiscovery ==<br />
<br />
By providing some DNS service name registrations for your domain and adding an additional rewrite-rule to the webserver's configuration, it's possible for some clients to automatically discover the account settings by just providing the user's e-mail address and password. The procedure is specified in [http://tools.ietf.org/html/rfc6764 RFC 6764]. <br />
<br />
The following example illustrates the DNS entries where MYSERVER.TLD would be the domain name of the ox-server, both for CalDAV and CardDAV via HTTP and HTTPS on the virtual host dav.MYSERVER.TLD:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
Additionally, a rewrite-rule similar to the following example should be added to the webserver configuration of the virtual host to enable the bootstrapping process:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:<br />
<br />
===com.openexchange.caldav.enabled===<br />
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
This means: In general CalDAV is turned off, but using the <code>contextSets</code> feature of the config cascade it is turned on for everyone that has infostore access.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years". <br />
<br />
===com.openexchange.caldav.url===<br />
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=21319Caldav carddav Bundles2016-01-14T16:16:21Z<p>Thomas.siedentopf: /* Alternative 1: Apache vhost (recommended) */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS Calendar and Address Book clients.<br />
<br />
CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDAV configuration in Mac OS X Mavericks and enter the path by hand. If you just want to enter the hostname, SSL is required. The same applies to iOS7 where SSL is always required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDAV configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:<br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for grizzly http service<br />
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass / balancer://oxserver-sync/servlet/dav/<br />
<br />
</VirtualHost><br />
<br />
If you use this method, you have to make sure that <code>dav.<MYSERVER.TLD></code> is reachable, your DNS configuration needs an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to <code>/tmp</code>.<br />
<br />
Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.<br />
<br />
$ vi <your-ox-site-configuration-file><br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Reminders [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address\ Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]<br />
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} eM\ Client [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.<br />
<br />
'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule .<br />
<br />
== Autodiscovery ==<br />
<br />
By providing some DNS service name registrations for your domain and adding an additional rewrite-rule to the webserver's configuration, it's possible for some clients to automatically discover the account settings by just providing the user's e-mail address and password. The procedure is specified in [http://tools.ietf.org/html/rfc6764 RFC 6764]. <br />
<br />
The following example illustrates the DNS entries where MYSERVER.TLD would be the domain name of the ox-server, both for CalDAV and CardDAV via HTTP and HTTPS on the virtual host dav.MYSERVER.TLD:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
Additionally, a rewrite-rule similar to the following example should be added to the webserver configuration of the virtual host to enable the bootstrapping process:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:<br />
<br />
===com.openexchange.caldav.enabled===<br />
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
This means: In general CalDAV is turned off, but using the <code>contextSets</code> feature of the config cascade it is turned on for everyone that has infostore access.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years". <br />
<br />
===com.openexchange.caldav.url===<br />
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=21318Caldav carddav Bundles2016-01-14T16:13:21Z<p>Thomas.siedentopf: /* Alternative 1: Apache vhost (recommended) */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS Calendar and Address Book clients.<br />
<br />
CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives. Please be aware that for a working Mavericks auto configuration setup you need to have SSL enabled on the server. The non-SSL variant described below only works if you use the advanced CalDAV configuration in Mac OS X Mavericks and enter the path by hand. If you just want to enter the hostname, SSL is required. The same applies to iOS7 where SSL is always required.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your site configuration file for OX so that ''' the existing OX configuration as well as the CalDAV/CardDAV configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
Please add the following entries before your existing <code>VirtualHost</code> entry. This is an <b>example</b> where <code>MYSERVER.TLD</code> is the domain-name of the ox-server:<br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.<MYSERVER.TLD><br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<br />
<Proxy balancer://oxserver-sync><br />
Order deny,allow<br />
Allow from all<br />
<br />
# for grizzly http service<br />
BalancerMember http://localhost:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX1<br />
# uncomment this entry if you have a clustered setup and want to use the other nodes too<br />
#BalancerMember http://<ip-of-other-host>:8009 timeout=100 smax=0 ttl=60 retry=60 loadfactor=50 route=OX2<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
ProxyPass / balancer://oxserver-sync/servlet/dav/<br />
<br />
</VirtualHost><br />
<br />
If you use this method, you have to make sure that <code>dav.<MYSERVER.TLD></code> is reachable, your DNS configuration needs an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to <code>/tmp</code>.<br />
<br />
Please note the <code>NameVirtualHost</code> directive is needed to be able to specify multiple virtual hosts for the same IP. The differentiation is only done by the given <code>ServerName</code>. This implies that you need two server names, so the virtual host entry for the existing ox site configuration needs to be also enriched by a <code>ServerName</code> if not already present. If you access the system without one of the given <code>ServerName</code>s so e.g. via the IP the system will pick the corresponding one by order (in this case the DAV part first. If you want it to work differently please change the order accordingly.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.<br />
<br />
$ vi <your-ox-site-configuration-file><br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Reminders [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address\ Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarAgent [OR]<br />
RewriteCond %{HTTP_USER_AGENT} accountsd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} eM\ Client [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
RewriteRule (.*) http://localhost:8009/servlet/dav$1 [P] # for grizzly http service<br />
<br />
'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.<br />
<br />
'''Note:''' Depending on the specific configuration, such a global definition of the rewrite rules might not be appropriate. However, the rules may also be defined inside a <code>Directory</code> context. More details are available at http://httpd.apache.org/docs/current/mod/mod_rewrite.html#rewriterule .<br />
<br />
== Autodiscovery ==<br />
<br />
By providing some DNS service name registrations for your domain and adding an additional rewrite-rule to the webserver's configuration, it's possible for some clients to automatically discover the account settings by just providing the user's e-mail address and password. The procedure is specified in [http://tools.ietf.org/html/rfc6764 RFC 6764]. <br />
<br />
The following example illustrates the DNS entries where MYSERVER.TLD would be the domain name of the ox-server, both for CalDAV and CardDAV via HTTP and HTTPS on the virtual host dav.MYSERVER.TLD:<br />
<br />
_caldavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_caldav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
_carddavs._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 443 dav.MYSERVER.TLD.<br />
_carddav._tcp.MYSERVER.TLD. 10800 IN SRV 10 1 80 dav.MYSERVER.TLD.<br />
<br />
Additionally, a rewrite-rule similar to the following example should be added to the webserver configuration of the virtual host to enable the bootstrapping process:<br />
<br />
RewriteEngine On<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/caldav [OR]<br />
RewriteCond %{REQUEST_URI} ^/\.well-known/carddav<br />
RewriteRule (.*) / [L,R]<br />
<br />
{{InstallPlugin|pluginname=open-xchange-dav|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}<br />
<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files <code>caldav.properties</code> and <code>caldav.yml</code>:<br />
<br />
===com.openexchange.caldav.enabled===<br />
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:<br />
<br />
/opt/open-xchange/etc/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
<br />
This means: In general CalDAV is turned off, but using the <code>contextSets</code> feature of the config cascade it is turned on for everyone that has infostore access.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years". <br />
<br />
===com.openexchange.caldav.url===<br />
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.<br />
<br />
[[Category: Clients]]<br />
[[Category: Administrator]]<br />
[[Category: AppSuite]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=CardDAVClients&diff=20926CardDAVClients2015-11-25T15:14:34Z<p>Thomas.siedentopf: /* Mac OS X Contacts */</p>
<hr />
<div>= Open-Xchange Contacts synchronization with CardDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CardDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Contacts ==<br />
<br />
For the Contacts application on Mac OS X 10.9 (Mavericks) and above, a CardDAV account can be configured as follows:<br />
<br />
{| <br />
| [[image:carddav-account5.png|thumb]] || style="width:85%" |<br />
* Click the "+" sign in Address Book -> Preferences -> Accounts.<br />
* In the "Account type" field keep "CardDAV" selected<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''usually with the prefix "dav." (e.g. "dav.myserver.tls")'''.<br />
* Click "Create"<br />
|}<br />
<br />
== iOS Contacts ==<br />
''Available since Open-Xchange Server v6.22''<br />
<br />
The iOS Contacts application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_carddav_config.png|thumb]] || style="width:85%" |<br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CardDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CardDAV interface:<br />
<br />
=== Unsupported Properties ===<br />
* Generally, only those contact properties that are also available on the Open-Xchange server are recognized and transferred into attributes of OX contacts<br />
* Starting with v7.8.0, the original vCard is also preserved, so that other extended or not mapped properties are still available there (see [[AppSuite:VCardMapping]] for details)<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CardDAV interface.<br />
* Due to various different handlings of representing distribution list members in vCards, distribution lists are excluded from syncrhonization via CardDAV.<br />
<br />
=== Unsupported Special Chars ===<br />
* The special char "/" in contact names is not supported. It will lead to an "HTTP/1.1 404 Not Found" error in webdav.<br />
<br />
=== Client Restrictions ===<br />
* The Mac Contacts App does not Support CalDAV Collections. Open-Xchange by default recognizes this and exposes an aggregated collection of the CalDAV Collections. As a consequence new contacts entered in subfolders on OX side will not appear in subfolders (or Contact Groups) on the Mac Contacts App but inside of the aggregated Collection itself. Additionally Contact Groups from the Contacts App are not synced to OX - however the Contacts itself will be synced to the OX Address Book. Creating a new Contacts Group from within the Contacts App using the OX CardDAV Account is not possible - the name will revert to “untitled group” and will not be synced to OX App Suite.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=File:Caldav-account4.png&diff=20925File:Caldav-account4.png2015-11-25T15:09:20Z<p>Thomas.siedentopf: Thomas.siedentopf uploaded a new version of &quot;File:Caldav-account4.png&quot;</p>
<hr />
<div></div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=AppSuite:CardDAVClients&diff=20924AppSuite:CardDAVClients2015-11-25T15:08:58Z<p>Thomas.siedentopf: /* Mac OS X Contacts */</p>
<hr />
<div>= Open-Xchange Contacts synchronization with CardDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CardDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Address Book / Contacts ==<br />
<br />
Depending on the used Mac OS X version, slightly different steps are necessary.<br />
<br />
=== Mac OS X Contacts ===<br />
{| <br />
| [[image:carddav-account5.png|thumb]] || style="width:85%" |<br />
* Choose "Contacts" -> "Add Account..." from the Contacts App main Menu<br />
* In the "Choose Contacts Account Provider..." Menu choose "Other Contacts Account..."<br />
* In the "Add a Contacts Account" Menu choose "CardDAV" and "Account Type" "Manual"<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''with the prefix "dav." (e.g. "dav.myserver.tld")'''.<br />
* Click "Sign In"<br />
|}<br />
<br />
'''PLEASE NOTE:''' For our product Open-Xchange Server Edition for UCS it isn't necessary to use "dav".<br />
<br />
=== Debug Options ===<br />
You can enable a Debug Menu inside the Address Book application which gives you access to advanced debugging and logging options. Please notice that some of these options may increase the size of the log files of your system and/or could also log sensitive data like passwords if enabled. Keep also in mind that any setting changed here will remain active until the setting itself will be reverted or changed again which means that disabling the Debug Menu itself is not sufficient to reset any debug settings to their defaults. All settings are case sensitive.<br />
<br />
Open a terminal window (Applications > Utilities > Terminal) and issue the following command for<br />
* enabling the Debug Menu in the AddressBook:<br />
defaults write com.apple.AddressBook ABShowDebugMenu -bool true<br />
* disabling the Debug Menu in the AddressBook:<br />
defaults write com.apple.AddressBook ABShowDebugMenu -bool false<br />
<br />
'''PLEASE NOTE:''': The debug menu is not available in Mac OS X 10.8.<br />
<br />
<br />
== iOS Contacts ==<br />
<br />
The iOS Contacts application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_carddav_config.png|thumb]] || style="width:85%" |<br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CardDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
'''PLEASE NOTE:''' For our product Open-Xchange Server Edition for UCS it isn't necessary to use "dav". <br />
<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CardDAV interface:<br />
<br />
=== Unsupported Properties ===<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CardDAV interface.<br />
<br />
[[Category: AppSuite]]<br />
[[Category: User]]<br />
[[Category: Clients]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=CalDAVClients&diff=20923CalDAVClients2015-11-25T15:08:43Z<p>Thomas.siedentopf: /* Mac OS X Calendar */</p>
<hr />
<div>= Open-Xchange Calendar synchronization with CalDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CalDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Calendar ==<br />
<br />
For the Calendar application on Mac OS X 10.9 (Mavericks) and above, a CalDAV account can be configured as follows:<br />
<br />
{| <br />
| [[image:caldav-account4.png|thumb]] || style="width:85%"| <br />
* Choose "Calendar" -> "Add Account..." from the Calendar App main Menu<br />
* In the "Choose Calendar Account Provider..." Menu choose "Other CalDAV-Account..."<br />
* In the "Add a CalDAV Account" Menu choose "Account Type" "Manual"<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''with the prefix "dav." (e.g. "dav.myserver.tld")'''.<br />
* Click "Sign In"<br />
|}<br />
<br />
=== Debug Options ===<br />
You can enable a Debug Menu inside the iCal application which gives you access to advanced debugging and logging options. Please notice that some of these options may increase the size of the log files of your system and/or could also log sensitive data like passwords if enabled. Keep also in mind that any setting changed here will remain active until the setting itself will be reverted or changed again which means that disabling the Debug Menu itself is not sufficient to reset any debug settings to their defaults. All settings are case sensitive.<br />
<br />
Open a terminal window (Applications > Utilities > Terminal) and issue the following command for<br />
* enabling the Debug Menu in iCal:<br />
defaults write com.apple.iCal CDB 1<br />
* disabling the Debug Menu in iCal:<br />
defaults write com.apple.iCal CDB 0<br />
* enabling CalDAV HTTP activity logging:<br />
defaults write com.apple.iCal LogHTTPActivity -boolean TRUE<br />
* disabling CalDAV HTTP activity logging:<br />
defaults write com.apple.iCal LogHTTPActivity -boolean FALSE<br />
<br />
'''Pay attention''': If you change these settings it might be needed to kill the CalendarAgent process with <code>killall CalendarAgent</code> just restarting the MacOS calendar application might not be enough. So in case you won't see any additional log output in the syslog, or the additional log output doesn't vanish after switching off these setting, please try killing the CalendarAgent process.<br />
<br />
== iOS Calendar ==<br />
<br />
The iOS Calendar application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_caldav_config.png|thumb]] || style="width:85%"| <br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CalDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
== Thunderbird/Lightning ==<br />
''Available since Open-Xchange Server v6.20.7''<br />
<br />
The steps below describe how to setup the Mozilla Thunderbird client with the Lightning Add-on. <br />
<br />
=== Prerequisites ===<br />
Please ensure that the following preconditions are met before continuing:<br />
* Latest versions of the Mozilla Thunderbird E-Mail client and the Lightning Add-on (check https://addons.mozilla.org/thunderbird/addon/lightning/ and http://www.mozilla.org/thunderbird/ for details)<br />
* In the Mozilla Thunderbird client, an E-Mail account for the user's Open-Xchange mailbox needs to be setup before configuring the CalDAV access<br />
<br />
=== Discover the CalDAV URL of your Calendar Folders ===<br />
In contrast to some other clients, Thunderbird/Lightning is not able to discover all the available calendar collections automatically. Instead, each calendar folder needs to be added seperately in the client. To do so, one needs to know the CalDAV URLs of the calendar folder that should be synchronized with the client. This URL is displayed in the properties-page in the Groupware web-interface.<br />
<br />
{| <br />
| [[image:CalDAV_URL_Step1.png|thumb]] || style="width:85%"| <br />
* Open a webbrowser and login to the groupware web-interface<br />
* From the folder tree, open the context menu of a calendar folder and select "Properties"<br />
|-<br />
| [[image:CalDAV_URL_Step2.png|thumb]] ||<br />
* The CalDAV URL is shown in the content area. Note down the URL or copy it to the clipboard.<br />
|}<br />
<br />
=== Add a Calendar in Thunderbird/Lightning ===<br />
As already mentioned, each Calendar folder that should be sychronized has to be added separately in the client. The following steps show how to add a Calendar in Thunderbird/Lightning. Before starting, ensure that the client is connected to the network and the server can be accessed.<br />
<br />
{| <br />
| [[image:LightningSetup_Step1.png|thumb]] || style="width:85%"| <br />
* Select "Events and Tasks" -> "Calendar" from the menu bar to switch to the Calendar view<br />
|-<br />
| [[image:LightningSetup_Step2.png|thumb]] || style="width:85%"| <br />
* From the menu bar, select "File" -> "New" -> "Calendar..."<br />
|-<br />
| [[image:LightningSetup_Step3.png|thumb]] || style="width:85%"| <br />
* In the popup window, select "On the network" and click "Next >"<br />
|-<br />
| [[image:LightningSetup_Step4.png|thumb]] || style="width:85%"| <br />
* As format, select "CalDAV"<br />
* Enter the CalDAV path as reported by the folder's properties page (see above) as location<br />
* For offline access, check the "Cache" checkbox <br />
* Click "Next >" to continue<br />
|-<br />
| [[image:LightningSetup_Step5.png|thumb]] || style="width:85%"| <br />
* Enter a name for the Calendar and assign a color if you like <br />
* Select whether reminders should be shown or not (recommended setting: off, see below for details)<br />
* Select the E-Mail account belonging to the Calendar user from the list <br />
* Click "Next >" to create the Calendar <br />
|-<br />
| [[image:LightningSetup_Step6.png|thumb]] || style="width:85%"| <br />
* When requested, enter your username and password for the server<br />
* Afterwards, the Calendar setup is complete and the contents are synchronized<br />
|}<br />
<br />
=== Debug Options ===<br />
In case of synchronization problems, the built-in error console of Mozilla Thunderbird may provide valuable information. The error console can be opened via "Tools" -> "Error Console". To increase the loglevel of the Lightning Add-on, open the config editor by selecting "Tools" -> "Options..." -> "Advanced" -> "Config Editor..." and set the properties "calendar.debug.log" and "calendar.debug.log.verbose" to "true".<br />
<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CalDAV interface:<br />
<br />
=== Reminders ===<br />
* While the iCalendar standard allows to set appointment reminders past due an appointment's start-date, the OX server is not able to save such alarm times and discards them.<br />
* Multiple reminders in an event are not supported by the OX server and are discarded.<br />
* Only reminders of type "DISPLAY" are supported by the OX server, reminders of other iCal types are discarded.<br />
* When dismissing reminders of recurring appointments in the Mozilla Lightning client, the reminder is removed from the whole recurring appointment object, since it's not possible to determine to which occurrence the dismiss action belongs to.<br />
* On iOS devices, when a custom default alert time is configured via Settings -> Mail, Contacts, Calendars -> Default Alert Times, this setting may also affect appointments you don't participate in. This is a client-specific feature and can't be influenced by the server.<br />
* Due to incompatible handling of reminders in the Mozilla Thunderbird / Lightning client, especially for reminders in recurring appointments, it's recommended to turn off reminders in synchronized calendar folders there (from the context menu of a calendar, select 'Properties' and uncheck 'Show Alarms').<br />
<br />
=== Unsupported Properties ===<br />
* Generally, only those appointment and task properties that are also available on the Open-Xchange server are used for synchronization, i.e. all unsupported properties are ignored and not saved.<br />
* The "URL" property for iCal resources is not supported by the OX server and is discarded.<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CalDAV interface.<br />
<br />
=== Private Appointments ===<br />
* Appointments classified as "private" are exported by the server with the "CLASS" property set to "PRIVATE".<br />
* iCal events with the "CLASS" property set to either "CONFIDENTIAL" or "PRIVATE" are treated in the same way by the server and are imported as "private" appointments.<br />
* Since "private" appointments with participants are not supported by the server, saving such an appointment results in the participants being removed implicitly during import.<br />
<br />
=== Tasks ===<br />
* Only simple tasks (no participants, no recurrence) are supported.<br />
* Only tasks from personal folders (no shared or public folders) are supported.<br />
* Only the properties "DTSTART", "DUE", "CATEGORIES", "SUMMARY", "PRIORITY", "DESCRIPTION", "VALARM", "STATUS", "PERCENT-COMPLETE" and "COMPLETED" are synchronized, other ones are discarded by the server.<br />
<br />
===Creating new Collections===<br />
* Creating a new collection in the client results in a new folder being created at the server, with the default calendar or tasks folder as its parent. <br />
* In the Mac OS clients, the name of a new folder may be need to set twice during creation, since the collection's location as chosen by the client changes once after sending it to the server. <br />
* Note: Due to the lacking support of the MKCALENDAR HTTP request in Apache's mod_ajp module, creating new collections currently only works when using the [[Grizzly]] package on the OX server.<br />
<br />
===Permissions in Shared Folders===<br />
* In a Calendar folder that is shared to the CalDAV user by another groupware user, the Mac OS iCal client does not allow editing appointments where the CalDAV user is not the organizer of the appointment, even if sufficient permissions were granted. This is a built-in restriction of the client, however, you are still able to edit or delete such appointments in the groupware web interface.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=File:Carddav-account5.png&diff=20922File:Carddav-account5.png2015-11-25T15:02:25Z<p>Thomas.siedentopf: Thomas.siedentopf uploaded a new version of &quot;File:Carddav-account5.png&quot;</p>
<hr />
<div></div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=AppSuite:CardDAVClients&diff=20921AppSuite:CardDAVClients2015-11-25T15:01:57Z<p>Thomas.siedentopf: /* Mac OS X Contacts */</p>
<hr />
<div>= Open-Xchange Contacts synchronization with CardDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CardDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Address Book / Contacts ==<br />
<br />
Depending on the used Mac OS X version, slightly different steps are necessary.<br />
<br />
=== Mac OS X Contacts ===<br />
{| <br />
| [[image:carddav-account5.png|thumb]] || style="width:85%" |<br />
* Choose "Contacts" -> "Add Account..." from the Contacts App main Menu<br />
* In the "Choose Contacts Account Provider..." Menu choose "Other Contacts Account..."<br />
* In the "Add a Contacts Account" Menu choose "CardDAV" and "Account Type" "Manual"<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''with the prefix "dav." (e.g. "dav.myserver.tld")'''.<br />
* Click "Create"<br />
|}<br />
<br />
'''PLEASE NOTE:''' For our product Open-Xchange Server Edition for UCS it isn't necessary to use "dav".<br />
<br />
=== Debug Options ===<br />
You can enable a Debug Menu inside the Address Book application which gives you access to advanced debugging and logging options. Please notice that some of these options may increase the size of the log files of your system and/or could also log sensitive data like passwords if enabled. Keep also in mind that any setting changed here will remain active until the setting itself will be reverted or changed again which means that disabling the Debug Menu itself is not sufficient to reset any debug settings to their defaults. All settings are case sensitive.<br />
<br />
Open a terminal window (Applications > Utilities > Terminal) and issue the following command for<br />
* enabling the Debug Menu in the AddressBook:<br />
defaults write com.apple.AddressBook ABShowDebugMenu -bool true<br />
* disabling the Debug Menu in the AddressBook:<br />
defaults write com.apple.AddressBook ABShowDebugMenu -bool false<br />
<br />
'''PLEASE NOTE:''': The debug menu is not available in Mac OS X 10.8.<br />
<br />
<br />
== iOS Contacts ==<br />
<br />
The iOS Contacts application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_carddav_config.png|thumb]] || style="width:85%" |<br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CardDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
'''PLEASE NOTE:''' For our product Open-Xchange Server Edition for UCS it isn't necessary to use "dav". <br />
<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CardDAV interface:<br />
<br />
=== Unsupported Properties ===<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CardDAV interface.<br />
<br />
[[Category: AppSuite]]<br />
[[Category: User]]<br />
[[Category: Clients]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=File:Ios_caldav_config.png&diff=20920File:Ios caldav config.png2015-11-25T14:33:07Z<p>Thomas.siedentopf: Thomas.siedentopf uploaded a new version of &quot;File:Ios caldav config.png&quot;</p>
<hr />
<div></div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=File:Ios_carddav_config.png&diff=20919File:Ios carddav config.png2015-11-25T14:31:07Z<p>Thomas.siedentopf: Thomas.siedentopf uploaded a new version of &quot;File:Ios carddav config.png&quot;</p>
<hr />
<div></div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=File:Ios_carddav_config.png&diff=20918File:Ios carddav config.png2015-11-25T14:22:17Z<p>Thomas.siedentopf: Thomas.siedentopf uploaded a new version of &quot;File:Ios carddav config.png&quot;</p>
<hr />
<div></div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=CardDAVClients&diff=20917CardDAVClients2015-11-25T14:09:30Z<p>Thomas.siedentopf: /* General Limitations */</p>
<hr />
<div>= Open-Xchange Contacts synchronization with CardDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CardDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Contacts ==<br />
<br />
For the Contacts application on Mac OS X 10.9 (Mavericks) and above, a CardDAV account can be configured as follows:<br />
<br />
{| <br />
| [[image:carddav-account5.png|thumb]] || style="width:85%" |<br />
* Click the "+" sign in Address Book -> Preferences -> Accounts.<br />
* In the "Account type" field keep "CardDAV" selected<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''usually with the prefix "dav." (e.g. "dav.MYSERVER.TLD")'''.<br />
* Click "Create"<br />
|}<br />
<br />
== iOS Contacts ==<br />
''Available since Open-Xchange Server v6.22''<br />
<br />
The iOS Contacts application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_carddav_config.png|thumb]] || style="width:85%" |<br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CardDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CardDAV interface:<br />
<br />
=== Unsupported Properties ===<br />
* Generally, only those contact properties that are also available on the Open-Xchange server are recognized and transferred into attributes of OX contacts<br />
* Starting with v7.8.0, the original vCard is also preserved, so that other extended or not mapped properties are still available there (see [[AppSuite:VCardMapping]] for details)<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CardDAV interface.<br />
* Due to various different handlings of representing distribution list members in vCards, distribution lists are excluded from syncrhonization via CardDAV.<br />
<br />
=== Unsupported Special Chars ===<br />
* The special char "/" in contact names is not supported. It will lead to an "HTTP/1.1 404 Not Found" error in webdav.<br />
<br />
=== Client Restrictions ===<br />
* The Mac Contacts App does not Support CalDAV Collections. Open-Xchange by default recognizes this and exposes an aggregated collection of the CalDAV Collections. As a consequence new contacts entered in subfolders on OX side will not appear in subfolders (or Contact Groups) on the Mac Contacts App but inside of the aggregated Collection itself. Additionally Contact Groups from the Contacts App are not synced to OX - however the Contacts itself will be synced to the OX Address Book. Creating a new Contacts Group from within the Contacts App using the OX CardDAV Account is not possible - the name will revert to “untitled group” and will not be synced to OX App Suite.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard&diff=19825AppSuite:OX Guard2015-07-06T10:51:29Z<p>Thomas.siedentopf: /* Mail Resolver */</p>
<hr />
<div>= OX Guard =<br />
<br />
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. <br />
<br />
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.<br />
<br />
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:<br />
<br />
* To setup a single server installation<br />
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster<br />
* To use the database service on the existing Open-Xchange installation for Guard, no replication<br />
* To provide a basic configuration setup, no mailserver configuration<br />
<br />
== Key features ==<br />
<br />
* Simple security at the touch of a button<br />
* Provides user based security - Separate from provider<br />
* Supplementary security to Provider based security - Layered<br />
* Powerful features yet simple to use and understand<br />
* Security - Inside and outside of the OX environment<br />
* Email and Drive integration<br />
* Uses proven PGP security<br />
<br />
== Availability ==<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
Please review following URL for remaining requirements <br />
<br />
Please review [[AppSuite:OX_System_Requirements#OX_Guard|OX Guard Requirements]] for a full list of requirements.<br />
<br />
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 without having any of the other Open-Xchange App Suite core services installed. OX App Suite v7.6.0 or later is required to operate this extension both in a single or multi server environments.<br />
<br />
Prerequisites:<br />
* Open-Xchange REST API<br />
* Grizzly HTTP connector (open-xchange-grizzly)<br />
* A supported Java Virtual Machine (Java 7)<br />
* An Open-Xchange App Suite installation v7.6.0 or later<br />
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages|Updating OX-Packages]] explains how that can be done.<br />
<br />
== Important Notes ==<br />
<br />
=== Customization ===<br />
<br />
OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Additional details will be provided in customization documentation. Check bottom of this page. <br />
<br />
<br />
=== Mail Resolver ===<br />
<br />
READ THIS VERY CAREFULLY; BEFORE PROCEEDING WITH GUARD INSTALLATION!<br />
<br />
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.<br />
<br />
Be sure to test the mail resolver using<br />
<br />
/opt/open-xchange/guard/sbin/guard test email@domain <br />
<br />
to see if the mail Resolver works.<br />
<br />
If the test does not work, you will likely need a custom Mail Resolver. Please see [[AppSuite:GuardMailResolver| Mail Resolver page]]<br />
<br />
This resolver software ''depends heavily on your local deployment''.<br />
<br />
= Download and Installation =<br />
<br />
=== General ===<br />
The installation of the open-xchange-rest package which is required for Guard will eventually execute database update tasks if installed and activated. Please take this into account.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|guard/stable/guard}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static<br />
<br />
=== Debian GNU/Linux 7.0 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|guard/stable/guard}}<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 11 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|guard/stable/guard}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static<br />
<br />
Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:<br />
<br />
$ update-alternatives --config java<br />
<br />
Now select the Java 1.7 JRE, example:<br />
<br />
There are 2 alternatives which provide `java'.<br />
<br />
Selection Alternative<br />
-----------------------------------------------<br />
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java<br />
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java<br />
<br />
Press enter to keep the default[*], or type selection number: 2<br />
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
'''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:<br />
<br />
oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME<br />
<br />
= Update OX Guard =<br />
<br />
Before upgrading Guard to version 2.0.0 you need to install the package <code>open-xchange-guard-backend</code> on all groupware nodes used by Guard throught the REST api. In other words, every groupware node have <code>open-xchange-rest</code> installed, now needs to have <code>open-xchange-guard-backend</code> installed.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum upgrade<br />
<br />
After the new packages are installed, the guard process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange-guard restart</pre><br />
<br />
=== Debian GNU/Linux 7.0 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}<br />
<br />
Then run<br />
<br />
$ apt-get update<br />
$ apt-get dist-upgrade<br />
<br />
If you want to see, what apt-get is going to do without actually doing it, you can run:<br />
<br />
$ apt-get dist-upgrade -s<br />
<br />
After the new packages are installed, the guard process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange-guard restart</pre><br />
<br />
=== SUSE Linux Enterprise Server 11 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}<br />
<br />
and run<br />
<br />
$ zypper dup -r guard-stable-guard-backend-updates<br />
$ zypper dup -r guard-stable-guard-ui-updates<br />
<br />
You might need to run<br />
<br />
$ zypper ref<br />
<br />
to update the repository metadata before running ''zypper up''.<br />
<br />
After the new packages are installed, the guard process needs a restart:<br />
<br />
<pre>$ open-xchange-guard restart</pre><br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
=== Update OX Guard v1.2 to OX Guard v2.0.0 ===<br />
<br />
If you have an existing Guard v1.2 database, and are upgrading to v2.0, additional PGP key table need to be created and populated. Once the Guard package has been updated, type<br />
<br />
/opt/open-xchange/guard/sbin/guard upgradePGP<br />
<br />
This process will alter the needed database tables and populate the needed lookup tables. Guard 1.2 can continue to run in the background. Once complete, Guard 2.0 can be started.<br />
<br />
= Configuration =<br />
<br />
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 guard.properties located in /opt/open-xchange/guard/etc. 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 here [[AppSuite:GuardConfiguration|Guard Configuration]]<br />
<br />
$ vim /opt/open-xchange/guard/etc/guard.properties<br />
<br />
Open-Xchange config_db host - Guard will establish a connection to the config_db<br />
<br />
com.openexchange.guard.configdbHostname=localhost<br />
<br />
Guard database for storing user keys<br />
<br />
com.openexchange.guard.oxguardDatabaseHostname=localhost<br />
<br />
Username and Password for the two databases above<br />
<br />
com.openexchange.guard.databaseUsername=openexchange<br />
com.openexchange.guard.databasePassword=db_password<br />
<br />
Open-Xchange REST API host<br />
<br />
com.openexchange.guard.restApiHostname=localhost<br />
<br />
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below)<br />
<br />
com.openexchange.guard.restApiUsername=apiusername<br />
com.openexchange.guard.restApiPassword=apipassword<br />
<br />
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients<br />
<br />
com.openexchange.guard.externalEmailURL=URL_TO_OX<br />
<br />
== Configure services ==<br />
<br />
=== Apache ===<br />
<br />
Configure the mod_proxy_http module by adding the Guard API.<br />
<br />
'''Redhat Enterprise Linux 6 or CentOS 6'''<br />
$ vim /etc/httpd/conf.d/proxy_http.conf<br />
<br />
'''Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11'''<br />
$ vim /etc/apache2/conf.d/proxy_http.conf<br />
<br />
<Proxy balancer://oxguard><br />
Order deny,allow<br />
Allow from all<br><br />
BalancerMember http://localhost:8080/oxguard timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br><br />
<br />
ProxyPass /appsuite/api/oxguard balancer://oxguard<br />
<br />
'''Please Note:''' The Guard API settings must be inserted before the existing “<Proxy /appsuite/api>” parameter.<br />
<br />
After the configuration is done, restart the Apache webserver<br />
<br />
$ apachectl restart<br />
<br />
=== Open-Xchange ===<br />
<br />
Starting in Guard 2.0, there is an administrative component to the Open-Xchange backend that notifies Guard when a user or context is deleted. Install the package open-xchange-guard-backend on all OX backend servers. On a debian install, this command would be:<br />
<br />
apt-get install open-xchange-guard-backend<br />
<br />
There is also a configuration file for the OX backend regarding some general Guard settings. Please remove comments in front of the following settings to the configuration file guard.properties on the Open-Xchange backend servers:<br />
<br />
$ vim /opt/open-xchange/etc/guard.properties<br />
<br />
# OX GUard general permission, required to activate Guard in the AppSuite UI.<br />
com.openexchange.capability.guard=true<br />
<br />
# Default theme template id for all users that have no custom template id configured.<br />
com.openexchange.guard.templateID=0<br />
<br />
Configure the API username and password that you assigned to Guard in the server.properties file<br />
<br />
$ vim /opt/open-xchange/etc/server.properties<br />
<br />
# Specify the user name used for HTTP basic auth by internal REST servlet<br />
com.openexchange.rest.services.basic-auth.login=apiusername<br />
<br />
# Specify the password used for HTTP basic auth by internal REST servlet<br />
com.openexchange.rest.services.basic-auth.password=apipassword<br />
<br />
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 /guardadmin<br />
<br />
$ vim /opt/open-xchange/etc/guard.properties<br />
<br />
# Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin<br />
# Default is empty<br />
com.openexchange.guard.endpoint=http://guardserver:8080/guardadmin<br />
<br />
<br />
Restart the OX backend<br />
<br />
$ /etc/init.d/open-xchange restart<br />
<br />
=== SELinux ===<br />
<br />
Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8080, which is where the Guard backend service listens to. In order to allow localhost connections to 8080 execute the following:<br />
<br />
$ setsebool -P httpd_can_network_connect 1<br />
<br />
== Initiating the Guard database and key store ==<br />
<br />
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 Guard databases. The administration script also takes care of the creation of the master keys and the master password file in /opt/open-xchange/guard. The initiation only needs to be done once for a multi server setup, for details please see “Optional / Clustering”.<br />
<br />
'''Please Note:''' If you run a cluster of OX / Guard nodes, only execute this command on ONE node. Not on all nodes! See [[AppSuite:GuardCluster | Ox Guard Clustering]] for details.<br />
<br />
/opt/open-xchange/guard/sbin/guard init<br />
<br />
'''Please Note:''' It is important to understand that the master password file located at /opt/open-xchange/guard/oxguardpass 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.<br />
<br />
== Test Setup ==<br />
<br />
Not required, but it is a good idea to test the Guard setup before starting the initialization. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.<br />
<br />
To test, use an email address that exists on the OX backend (john@example.com for this example)<br />
<br />
/opt/open-xchange/guard/sbin/guard test john@example.com<br />
<br />
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.<br />
<br />
<br />
== Start Guard ==<br />
<br />
The services have been configured and the database has been initiated, it's time to start Guard<br />
<br />
$ /etc/init.d/open-xchange-guard start<br />
<br />
== Enabling Guard for Users ==<br />
<br />
Guard provides two capabilities for users in the environment as well as a basic "core" level:<br />
<br />
* '''Guard:''' com.openexchange.capability.guard<br />
* '''Guard Mail:''' com.openexchange.capability.guard-mail<br />
* '''Guard Drive:''' com.openexchange.capability.guard-drive<br />
<br />
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.<br />
<br />
"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.<br />
<br />
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:<br />
<br />
'''Guard Mail:'''<br />
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true<br />
<br />
'''Guard Drive:'''<br />
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true<br />
<br />
'''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 guard.properties file on the OX bakend<br />
<br />
== Optional ==<br />
<br />
=== SSL Configuration ===<br />
<br />
Per default the connection between the Guard backend and the configured Open-Xchange REST API host is unencrypted. Even though that Guard will never transmit unencrypted emails to or from the REST API you can optionally encrypt the whole communication between those two components by using SSL. To enforce Guard to use SSL in the communication between those two components enable the follwing configuration in Guard configuration file. <br />
<br />
$ vim /opt/open-xchange/guard/etc/guard.properties<br />
<br />
com.openexchange.guard.backend_ssl=true<br />
<br />
The Guard backend is most commonly placed behind a load balancer (APACHE or other) and defaults to HTTP for incoming and outgoing traffic, using the load balancer to do SSL with the users. If you want Guard to use SSL for all communications, you need to set up the SSL key to use.<br />
<br />
Please note that you have to provide access to the certificates.<br />
<br />
com.openexchange.guard.useSSL: true<br />
com.openexchange.guard.SSLPort: 8443<br />
com.openexchange.guard.SSLKeyStore: //keystore location//<br />
com.openexchange.guard.SSLKeyName: //alias name here//<br />
com.openexchange.guard.SSLKeyPass: //ssl password//<br />
<br />
'''Please Note:''' Enabling SSL might decrease performance and/or create more system load due to additional encoding of the HTTP streams.<br />
<br />
For details on SSL installation and configuration, please see [[AppSuite:GuardSSL|OX Guard SSL Installation]]<br />
<br />
== Recipient key detection ==<br />
<br />
=== Local ===<br />
<br />
Guard needs to determine if an email recipients email address is an internal or external (non-ox) user. <br />
<br />
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 com.openexchange.mailmapping.MailResolver class or by interfacing Guard with your mail resolver system.<br />
Please see [[Appsuite:GuardMailResolver|OX Guard Mail Resolver]] for details<br />
<br />
=== External ===<br />
<br />
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].<br />
<br />
External PGP servers to use can be configured in the guard.properties file on the Guard servers.<br />
<br />
com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371<br />
<br />
If you would like this Guard installation discoverable by other Guard servers, then create a SRV record for each domain ("example.com" in this illustration)<br />
<br />
_hkp._tcp.example.com<br />
<br />
You will also need to make additional entries in the apache proxy_http.conf file.<br />
<br />
<Proxy balancer://oxguardpgp><br />
Order deny,allow<br />
Allow from all, add<br />
BalancerMember http://guardserver:8080/pgp timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX3<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
<Proxy /pks><br />
ProxyPass balancer://oxguardpgp<br />
</Proxy><br />
<br />
'''Please Note''' PGP Public key servers by default append use the url server/pks when the record is obtained from a SRV record. The proxy above routes anything with the apache domain/pks to the Oxguard PGP server<br />
<br />
== Clustering ==<br />
<br />
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.<br />
<br />
=== MySQL ===<br />
<br />
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 my.cnf:<br />
<br />
bind = 0.0.0.0<br />
<br />
This allows the Guard backend to bind to the MySQL host which is configured in the guard.properties file with com.openexchange.guard.configdbHostname. 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:<br />
<br />
GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;<br />
<br />
=== Apache ===<br />
<br />
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 mod_proxy we need to add a servlet called "preliminary" to proxy_http.conf, example based on a clustered mod_proxy configuration:<br />
<br />
<Location /preliminary><br />
Order Deny,Allow<br />
Deny from all<br />
# Only allow access from Guard servers within the network. Do not expose this<br />
# location outside of your network. In case you use a load balancing service in front<br />
# of your Apache infrastructure you should make sure that access to /preliminary will<br />
# be blocked from the internet / outside clients. Examples:<br />
# Allow from 192.168.0.1<br />
# Allow from 192.168.1.1 192.168.1.2<br />
# Allow from 192.168.0.<br />
ProxyPass /preliminary balancer://oxcluster/preliminary<br />
</Location><br />
<br />
Make sure that the balancer is properly configured in the mod_proxy 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 /preliminary 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 /preliminary from WAN to restrict access to the servlet to internal network services only.<br />
<br />
Now add the OX Guard BalancerMembers to the oxguard balancer configuration (also in proxy_http.conf) 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.<br />
<br />
If the Apache server is a dedicated server / 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):<br />
<br />
$ apt-get install open-xchange-guard-ui-static<br />
<br />
=== Open-Xchange ===<br />
<br />
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:<br />
<br />
$ vim /opt/open-xchange/etc/server.properties<br />
<br />
and set:<br />
<br />
com.openexchange.IPCheck=false<br />
<br />
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):<br />
<br />
$ apt-get install open-xchange-guard-ui<br />
<br />
Restart the Open-Xchange service afterwards.<br />
<br />
=== OX Guard ===<br />
<br />
For details in clustering Guard servers, please see [[AppSuite:GuardCluster | OxGuard Clustering]] . It is critical that all Guard servers have the same oxguardpass file. Please see the clustering link for details. Do not run ./guard init on more than one server.<br />
<br />
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 /opt/open-xchange/guard/etc/guard.properties:<br />
<br />
com.openexchange.guard.restApiHostname=apache.example.com<br />
<br />
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 serblet /preliminary 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 /opt/open-xchange/guard/etc/guard.properties:<br />
<br />
com.openexchange.guard.oxBackendPort=80<br />
<br />
Please also change all settings in regards to MySQL like com.openexchange.guard.configdbHostname, com.openexchange.guard.oxguardDatabaseHostname, com.openexchange.guard.databaseUsername or com.openexchange.guard.databasePassword. Afterwards restart the OX Guard service and check the logfile if the OX Guard backend is able to connect to the configured REST API.<br />
<br />
= Support API =<br />
<br />
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.<br />
The OX Guard support API is accessible using: /guardsupport. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard.properties file using the following settings:<br />
<br />
<code><br />
# Specify the username and password for accessing the Support API of Guard<br />
com.openexchange.guard.supportapiusername=<br />
com.openexchange.guard.supportapipassword=<br />
</code><br />
<br />
=== Reset password ===<br />
POST <code>/guardsupport/?action=reset_password</code><br />
<br />
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.<br />
<br />
Since Guard 2.0<br />
<br />
Parameters:<br />
* <code>email</code> – The email address of the user to reset the password for<br />
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address<br />
<br />
=== Expose key ===<br />
<br />
POST <code>/guardsupport/?action=expose_key</code><br />
<br />
Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key.<br />
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.<br />
<br />
Since Guard 2.0<br />
<br />
Parameters:<br />
* <code>email</code> – The email address of the user to expose the deleted keys for<br />
* <code>cid</code> – The context id<br />
<br />
Response:<br />
An URL pointing to the downloadable exposed keys<br />
<br />
=== Delete user ===<br />
<br />
POST <code>/guardsupport/?action=delete_user</code><br />
<br />
Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call.<br />
<br />
Since Guard 2.0<br />
<br />
Parameters:<br />
* <code>user_id</code> – The user's id<br />
* <code>cid</code> - The context id<br />
<br />
= Customization =<br />
<br />
Guard's templates are customizable at the user and context level. Please see [[AppSuite:GuardCustomization| Customization]] for details<br />
<br />
= Entropy =<br />
<br />
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 [[AppSuite:GuardEntropy | Entropy]] for a possible solution</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Guard&diff=19804AppSuite:OX Guard2015-07-02T13:59:13Z<p>Thomas.siedentopf: /* Open-Xchange */</p>
<hr />
<div>= OX Guard =<br />
<br />
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. <br />
<br />
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.<br />
<br />
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:<br />
<br />
* To setup a single server installation<br />
* To setup a single Guard instance on an existing Open-Xchange installation, no cluster<br />
* To use the database service on the existing Open-Xchange installation for Guard, no replication<br />
* To provide a basic configuration setup, no mailserver configuration<br />
<br />
== Key features ==<br />
<br />
* Simple security at the touch of a button<br />
* Provides user based security - Separate from provider<br />
* Supplementary security to Provider based security - Layered<br />
* Powerful features yet simple to use and understand<br />
* Security - Inside and outside of the OX environment<br />
* Email and Drive integration<br />
* Uses proven PGP security<br />
<br />
== Availability ==<br />
<br />
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.<br />
<br />
== Requirements ==<br />
<br />
Please review following URL for remaining requirements <br />
<br />
Please review [[AppSuite:OX_System_Requirements#OX_Guard|OX Guard Requirements]] for a full list of requirements.<br />
<br />
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 without having any of the other Open-Xchange App Suite core services installed. OX App Suite v7.6.0 or later is required to operate this extension both in a single or multi server environments.<br />
<br />
Prerequisites:<br />
* Open-Xchange REST API<br />
* Grizzly HTTP connector (open-xchange-grizzly)<br />
* A supported Java Virtual Machine (Java 7)<br />
* An Open-Xchange App Suite installation v7.6.0 or later<br />
* Please Note: To get access to the latest minor features and bug fixes, you need to have a valid license. The article [[AppSuite:UpdatingOXPackages|Updating OX-Packages]] explains how that can be done.<br />
<br />
== Important Notes ==<br />
<br />
=== Customization ===<br />
<br />
OX Guard version supports branding / theming using the configuration cascade, defining a templateID for a user or context. Additional details will be provided in customization documentation. Check bottom of this page. <br />
<br />
<br />
=== Mail Resolver ===<br />
<br />
Your GUARD installation may require a custom Mailresolver, which basically checks, if an eMail address can be mapped to an AppSuite user or not. This depends heavily on your local deployment. For more details, check out the [[AppSuite:GuardMailResolver| Mail Resolver page]]<br />
<br />
= Download and Installation =<br />
<br />
=== General ===<br />
The installation of the open-xchange-rest package which is required for Guard will eventually execute database update tasks if installed and activated. Please take this into account.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|guard/stable/guard}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static<br />
<br />
=== Debian GNU/Linux 7.0 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|guard/stable/guard}}<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static<br />
<br />
=== SUSE Linux Enterprise Server 11 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|guard/stable/guard}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-rest open-xchange-guard open-xchange-guard-ui open-xchange-guard-ui-static<br />
<br />
Guard requires Java 1.7, which will be installed through the Guard packages, still SUSE Linux Enterprise Server 11 will not use Java 1.7 by default. Therefor we have to set Java 1.7 as the default instead of Java 1.6:<br />
<br />
$ update-alternatives --config java<br />
<br />
Now select the Java 1.7 JRE, example:<br />
<br />
There are 2 alternatives which provide `java'.<br />
<br />
Selection Alternative<br />
-----------------------------------------------<br />
* 1 /usr/lib64/jvm/jre-1.6.0-ibm/bin/java<br />
+ 2 /usr/lib64/jvm/jre-1.7.0-ibm/bin/java<br />
<br />
Press enter to keep the default[*], or type selection number: 2<br />
Using '/usr/lib64/jvm/jre-1.7.0-ibm/bin/java' to provide 'java'.<br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
'''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:<br />
<br />
oxguard/cfg/guard.properties/com.openexchange.guard.externalEmailURL=HOSTNAME.DOMAINNAME<br />
<br />
= Update OX Guard =<br />
<br />
Before upgrading Guard to version 2.0.0 you need to install the package <code>open-xchange-guard-backend</code> on all groupware nodes used by Guard throught the REST api. In other words, every groupware node have <code>open-xchange-rest</code> installed, now needs to have <code>open-xchange-guard-backend</code> installed.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum upgrade<br />
<br />
After the new packages are installed, the guard process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange-guard restart</pre><br />
<br />
=== Debian GNU/Linux 7.0 ===<br />
<br />
If not already done, add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}<br />
<br />
Then run<br />
<br />
$ apt-get update<br />
$ apt-get dist-upgrade<br />
<br />
If you want to see, what apt-get is going to do without actually doing it, you can run:<br />
<br />
$ apt-get dist-upgrade -s<br />
<br />
After the new packages are installed, the guard process needs a restart:<br />
<br />
<pre>$ /etc/init.d/open-xchange-guard restart</pre><br />
<br />
=== SUSE Linux Enterprise Server 11 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|guard/stable/guard/updates}}<br />
<br />
and run<br />
<br />
$ zypper dup -r guard-stable-guard-backend-updates<br />
$ zypper dup -r guard-stable-guard-ui-updates<br />
<br />
You might need to run<br />
<br />
$ zypper ref<br />
<br />
to update the repository metadata before running ''zypper up''.<br />
<br />
After the new packages are installed, the guard process needs a restart:<br />
<br />
<pre>$ open-xchange-guard restart</pre><br />
<br />
=== Univention Corporate Server ===<br />
<br />
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.<br />
<br />
=== Update OX Guard v1.2 to OX Guard v2.0.0 ===<br />
<br />
If you have an existing Guard v1.2 database, and are upgrading to v2.0, additional PGP key table need to be created and populated. Once the Guard package has been updated, type<br />
<br />
/opt/open-xchange/guard/sbin/guard upgradePGP<br />
<br />
This process will alter the needed database tables and populate the needed lookup tables. Guard 1.2 can continue to run in the background. Once complete, Guard 2.0 can be started.<br />
<br />
= Configuration =<br />
<br />
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 guard.properties located in /opt/open-xchange/guard/etc. 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 here [[AppSuite:GuardConfiguration|Guard Configuration]]<br />
<br />
$ vim /opt/open-xchange/guard/etc/guard.properties<br />
<br />
Open-Xchange config_db host - Guard will establish a connection to the config_db<br />
<br />
com.openexchange.guard.configdbHostname=localhost<br />
<br />
Guard database for storing user keys<br />
<br />
com.openexchange.guard.oxguardDatabaseHostname=localhost<br />
<br />
Username and Password for the two databases above<br />
<br />
com.openexchange.guard.databaseUsername=openexchange<br />
com.openexchange.guard.databasePassword=db_password<br />
<br />
Open-Xchange REST API host<br />
<br />
com.openexchange.guard.restApiHostname=localhost<br />
<br />
Open-Xchange REST API username and password (need to be defined in the OX backend in the "Configure services" below)<br />
<br />
com.openexchange.guard.restApiUsername=apiusername<br />
com.openexchange.guard.restApiPassword=apipassword<br />
<br />
External URL for this Open-Xchange installation. This setting will be used to generate the link to the secure content for external recipients<br />
<br />
com.openexchange.guard.externalEmailURL=URL_TO_OX<br />
<br />
== Configure services ==<br />
<br />
=== Apache ===<br />
<br />
Configure the mod_proxy_http module by adding the Guard API.<br />
<br />
'''Redhat Enterprise Linux 6 or CentOS 6'''<br />
$ vim /etc/httpd/conf.d/proxy_http.conf<br />
<br />
'''Debian GNU/Linux 7.0 and SUSE Linux Enterprise Server 11'''<br />
$ vim /etc/apache2/conf.d/proxy_http.conf<br />
<br />
<Proxy balancer://oxguard><br />
Order deny,allow<br />
Allow from all<br><br />
BalancerMember http://localhost:8080/oxguard timeout=1800 smax=0 ttl=60 retry=60 loadfactor=100 route=OX1<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br><br />
<br />
ProxyPass /appsuite/api/oxguard balancer://oxguard<br />
<br />
'''Please Note:''' The Guard API settings must be inserted before the existing “<Proxy /appsuite/api>” parameter.<br />
<br />
After the configuration is done, restart the Apache webserver<br />
<br />
$ apachectl restart<br />
<br />
=== Open-Xchange ===<br />
<br />
Starting in Guard 2.0, there is an administrative component to the Open-Xchange backend that notifies Guard when a user or context is deleted. Install the package open-xchange-guard-backend on all OX backend servers. On a debian install, this command would be:<br />
<br />
apt-get install open-xchange-guard-backend<br />
<br />
There is also a configuration file for the OX backend regarding some general Guard settings. Please remove comments in front of the following settings to the configuration file guard.properties on the Open-Xchange backend servers:<br />
<br />
$ vim /opt/open-xchange/etc/guard.properties<br />
<br />
# OX GUard general permission, required to activate Guard in the AppSuite UI.<br />
com.openexchange.capability.guard=true<br />
<br />
# Default theme template id for all users that have no custom template id configured.<br />
com.openexchange.guard.templateID=0<br />
<br />
Configure the API username and password that you assigned to Guard in the server.properties file<br />
<br />
$ vim /opt/open-xchange/etc/server.properties<br />
<br />
# Specify the user name used for HTTP basic auth by internal REST servlet<br />
com.openexchange.rest.services.basic-auth.login=apiusername<br />
<br />
# Specify the password used for HTTP basic auth by internal REST servlet<br />
com.openexchange.rest.services.basic-auth.password=apipassword<br />
<br />
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 /guardadmin<br />
<br />
$ vim /opt/open-xchange/etc/guard.properties<br />
<br />
# Specifies the URI to the OX Guard end-point; e.g. http://guard.host.invalid:8081/guardadmin<br />
# Default is empty<br />
com.openexchange.guard.endpoint=http://guardserver:8080/guardadmin<br />
<br />
<br />
Restart the OX backend<br />
<br />
$ /etc/init.d/open-xchange restart<br />
<br />
=== SELinux ===<br />
<br />
Running SELinux prohibits your local Open-Xchange backend service to connect to localhost:8080, which is where the Guard backend service listens to. In order to allow localhost connections to 8080 execute the following:<br />
<br />
$ setsebool -P httpd_can_network_connect 1<br />
<br />
== Initiating the Guard database and key store ==<br />
<br />
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 Guard databases. The administration script also takes care of the creation of the master keys and the master password file in /opt/open-xchange/guard. The initiation only needs to be done once for a multi server setup, for details please see “Optional / Clustering”.<br />
<br />
'''Please Note:''' If you run a cluster of OX / Guard nodes, only execute this command on ONE node. Not on all nodes!<br />
<br />
/opt/open-xchange/guard/sbin/guard init<br />
<br />
'''Please Note:''' It is important to understand that the master password file located at /opt/open-xchange/guard/oxguardpass 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.<br />
<br />
== Test Setup ==<br />
<br />
Not required, but it is a good idea to test the Guard setup before starting the initialization. The test function will verify that Guard has a good connection to the OX backend, and that it can resolve email addresses to users.<br />
<br />
To test, use an email address that exists on the OX backend (john@example.com for this example)<br />
<br />
/opt/open-xchange/guard/sbin/guard test john@example.com<br />
<br />
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.<br />
<br />
<br />
== Start Guard ==<br />
<br />
The services have been configured and the database has been initiated, it's time to start Guard<br />
<br />
$ /etc/init.d/open-xchange-guard start<br />
<br />
== Enabling Guard for Users ==<br />
<br />
Guard provides two capabilities for users in the environment as well as a basic "core" level:<br />
<br />
* '''Guard:''' com.openexchange.capability.guard<br />
* '''Guard Mail:''' com.openexchange.capability.guard-mail<br />
* '''Guard Drive:''' com.openexchange.capability.guard-drive<br />
<br />
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.<br />
<br />
"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.<br />
<br />
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:<br />
<br />
'''Guard Mail:'''<br />
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-mail=true<br />
<br />
'''Guard Drive:'''<br />
$ /opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --config/com.openexchange.capability.guard-drive=true<br />
<br />
'''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 guard.properties file on the OX bakend<br />
<br />
== Optional ==<br />
<br />
=== SSL Configuration ===<br />
<br />
Per default the connection between the Guard backend and the configured Open-Xchange REST API host is unencrypted. Even though that Guard will never transmit unencrypted emails to or from the REST API you can optionally encrypt the whole communication between those two components by using SSL. To enforce Guard to use SSL in the communication between those two components enable the follwing configuration in Guard configuration file. <br />
<br />
$ vim /opt/open-xchange/guard/etc/guard.properties<br />
<br />
com.openexchange.guard.backend_ssl=true<br />
<br />
The Guard backend is most commonly placed behind a load balancer (APACHE or other) and defaults to HTTP for incoming and outgoing traffic, using the load balancer to do SSL with the users. If you want Guard to use SSL for all communications, you need to set up the SSL key to use.<br />
<br />
Please note that you have to provide access to the certificates.<br />
<br />
com.openexchange.guard.useSSL: true<br />
com.openexchange.guard.SSLPort: 8443<br />
com.openexchange.guard.SSLKeyStore: //keystore location//<br />
com.openexchange.guard.SSLKeyName: //alias name here//<br />
com.openexchange.guard.SSLKeyPass: //ssl password//<br />
<br />
'''Please Note:''' Enabling SSL might decrease performance and/or create more system load due to additional encoding of the HTTP streams.<br />
<br />
For details on SSL installation and configuration, please see [[AppSuite:GuardSSL|OX Guard SSL Installation]]<br />
<br />
== Recipient key detection ==<br />
<br />
=== Local ===<br />
<br />
Guard needs to determine if an email recipients email address is an internal or external (non-ox) user. <br />
<br />
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 com.openexchange.mailmapping.MailResolver class or by interfacing Guard with your mail resolver system.<br />
Please see [[Appsuite:GuardMailResolver|OX Guard Mail Resolver]] for details<br />
<br />
=== External ===<br />
<br />
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].<br />
<br />
External PGP servers to use can be configured in the guard.properties file on the Guard servers.<br />
<br />
com.openexchange.guard.publicPGPDirectory = hkp://keys.gnupg.net:11371, hkp://pgp.mit.edu:11371<br />
<br />
If you would like this Guard installation discoverable by other Guard servers, then create a SRV record for each domain ("example.com" in this illustration)<br />
<br />
_hkp._tcp.example.com<br />
<br />
You will also need to make additional entries in the apache proxy_http.conf file.<br />
<br />
<Proxy balancer://oxguardpgp><br />
Order deny,allow<br />
Allow from all, add<br />
BalancerMember http://guardserver:8080/pgp timeout=1800 smax=0 ttl=60 retry=60 loadfactor=50 route=OX3<br />
ProxySet stickysession=JSESSIONID|jsessionid scolonpathdelim=ON<br />
SetEnv proxy-initial-not-pooled<br />
SetEnv proxy-sendchunked<br />
</Proxy><br />
<br />
<Proxy /pks><br />
ProxyPass balancer://oxguardpgp<br />
</Proxy><br />
<br />
'''Please Note''' PGP Public key servers by default append use the url server/pks when the record is obtained from a SRV record. The proxy above routes anything with the apache domain/pks to the Oxguard PGP server<br />
<br />
== Clustering ==<br />
<br />
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.<br />
<br />
=== MySQL ===<br />
<br />
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 my.cnf:<br />
<br />
bind = 0.0.0.0<br />
<br />
This allows the Guard backend to bind to the MySQL host which is configured in the guard.properties file with com.openexchange.guard.configdbHostname. 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:<br />
<br />
GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'oxguard.example.com' IDENTIFIED BY ‘secret’;<br />
<br />
=== Apache ===<br />
<br />
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 mod_proxy we need to add a servlet called "preliminary" to proxy_http.conf, example based on a clustered mod_proxy configuration:<br />
<br />
<Location /preliminary><br />
Order Deny,Allow<br />
Deny from all<br />
# Only allow access from Guard servers within the network. Do not expose this<br />
# location outside of your network. In case you use a load balancing service in front<br />
# of your Apache infrastructure you should make sure that access to /preliminary will<br />
# be blocked from the internet / outside clients. Examples:<br />
# Allow from 192.168.0.1<br />
# Allow from 192.168.1.1 192.168.1.2<br />
# Allow from 192.168.0.<br />
ProxyPass /preliminary balancer://oxcluster/preliminary<br />
</Location><br />
<br />
Make sure that the balancer is properly configured in the mod_proxy 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 /preliminary 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 /preliminary from WAN to restrict access to the servlet to internal network services only.<br />
<br />
Now add the OX Guard BalancerMembers to the oxguard balancer configuration (also in proxy_http.conf) 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.<br />
<br />
If the Apache server is a dedicated server / 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):<br />
<br />
$ apt-get install open-xchange-guard-ui-static<br />
<br />
=== Open-Xchange ===<br />
<br />
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:<br />
<br />
$ vim /opt/open-xchange/etc/server.properties<br />
<br />
and set:<br />
<br />
com.openexchange.IPCheck=false<br />
<br />
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):<br />
<br />
$ apt-get install open-xchange-guard-ui<br />
<br />
Restart the Open-Xchange service afterwards.<br />
<br />
=== OX Guard ===<br />
<br />
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 /opt/open-xchange/guard/etc/guard.properties:<br />
<br />
com.openexchange.guard.restApiHostname=apache.example.com<br />
<br />
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 serblet /preliminary 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 /opt/open-xchange/guard/etc/guard.properties:<br />
<br />
com.openexchange.guard.oxBackendPort=80<br />
<br />
Please also change all settings in regards to MySQL like com.openexchange.guard.configdbHostname, com.openexchange.guard.oxguardDatabaseHostname, com.openexchange.guard.databaseUsername or com.openexchange.guard.databasePassword. Afterwards restart the OX Guard service and check the logfile if the OX Guard backend is able to connect to the configured REST API.<br />
<br />
= Support API =<br />
<br />
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.<br />
The OX Guard support API is accessible using: /guardsupport. A client has to do a BASIC AUTH authentication in order to access the API. Username and password can be configured in the guard.properties file using the following settings:<br />
<br />
<code><br />
# Specify the username and password for accessing the Support API of Guard<br />
com.openexchange.guard.supportapiusername=<br />
com.openexchange.guard.supportapipassword=<br />
</code><br />
<br />
=== Reset password ===<br />
POST <code>/guardsupport/?action=reset_password</code><br />
<br />
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.<br />
<br />
Since Guard 2.0<br />
<br />
Parameters:<br />
* <code>email</code> – The email address of the user to reset the password for<br />
* <code>default</code> (optional) – The email address to send the new password to, if the user did not specify a secondary email address<br />
<br />
=== Expose key ===<br />
<br />
POST <code>/guardsupport/?action=expose_key</code><br />
<br />
Marks a deleted user key temporary as “exposed” and creates a unique URL for downloading the exposed key.<br />
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.<br />
<br />
Since Guard 2.0<br />
<br />
Parameters:<br />
* <code>email</code> – The email address of the user to expose the deleted keys for<br />
* <code>cid</code> – The context id<br />
<br />
Response:<br />
An URL pointing to the downloadable exposed keys<br />
<br />
=== Delete user ===<br />
<br />
POST <code>/guardsupport/?action=delete_user</code><br />
<br />
Deletes all keys related to a certain user. The keys are backed up and can be exposed using the “expose_key” call.<br />
<br />
Since Guard 2.0<br />
<br />
Parameters:<br />
* <code>user_id</code> – The user's id<br />
* <code>cid</code> - The context id<br />
<br />
= Customization =<br />
<br />
Guard's templates are customizable at the user and context level. Please see [[AppSuite:GuardCustomization| Customization]] for details<br />
<br />
= Entropy =<br />
<br />
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 [[AppSuite:GuardEntropy | Entropy]] for a possible solution</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=18447HTTP API2014-09-15T08:39:47Z<p>Thomas.siedentopf: /* Form Login (since 6.20) */</p>
<hr />
<div>== Introduction ==<br />
<br />
This document defines the Open-Xchange HTTP API which is used by the new AJAX GUI. The first chapter describes general definitions and conventions which apply to all server modules. All other chapters describe individual server modules.<br />
<br />
=== Low level protocol ===<br />
<br />
The client accesses the server through HTTP GET, POST and PUT requests. HTTP cookies are used for authentication and must therefore be processed and sent back by the client as specified by [http://tools.ietf.org/html/rfc6265 RFC 6265]. The HTTP API is accessible at URIs starting with <code>/ajax</code>. Each server module has a unique name and its own sub-namespace with that name below <code>/ajax</code>, e. g. all access to the module "tasks" is via URIs starting with <code>/ajax/tasks</code>.<br />
<br />
Text encoding is always UTF-8. Data is sent from the server to the client as <code>text/javascript</code> and interpreted by the client to obtain an ECMAScript object. The HTTP API uses only a small subset of the ECMAScript syntax. This subset is roughly described by the following BNF:<br />
<br />
Value ::= "null" | Boolean | Number | String | Array | Object<br />
Boolean ::= "true" | "false"<br />
Number ::= see NumericLiteral in ECMA 262 3rd edition<br />
String ::= \"([^"\n\\]|\\["\n\\])*\"<br />
Array ::= "[]" | "[" Value ("," Value)* "]"<br />
Object ::= "{}" | "{" Name ":" Value ("," Name ":" Value)* "}"<br />
Name ::= [A-Fa-f][0-9A-Fa-f_]*<br />
<br />
Numbers are the standard signed integer and floating point numbers. Strings can contain any character, except double quotes, newlines and backslashes, which must be escaped by a backslash. Control characters in strings (other than newline) are not supported. Whitespace is allowed between any two tokens. See [http://json.org JSON] and [http://www.ecma-international.org/publications/standards/Ecma-262.htm ECMA 262, 3<sup>rd</sup> edition] for the formal definition.<br />
<br />
The response body consists of an object, which contains up to four fields as described in [[#ResponseBody | Response body]]. The field <code>data</code> contains the actual payload which is described in following chapters. The fields <code>timestamp</code>, <code>error</code> and <code>error_params</code> are present when data objects are returned, if an error occurred and if the error message contains conversion specifiers, respectively. Following sections describe the contents of these fields in more detail.<br />
<br />
{| id="ResponseBody" cellspacing="0" border="1"<br />
|+ align="bottom" | Response body<br />
! Name !! Type !! Value<br />
|-<br />
| data || Value || Payload of the response.<br />
|-<br />
| timestamp || Timestamp || The latest timestamp of the returned data (see [[HTTP_API#Updates|Updates]]).<br />
|-<br />
| error || String || The translated error message. Present in case of errors.<br />
|-<br />
| error_params || Array || As o 7.4.2: Empty JSON array. Before that: Parameters for the error message that would need to be replaced in the error string (in a printf-format style).<br />
|-<br />
| error_id || String || Unique error identifier to help finding this error instance in the server logs.<br />
|-<br />
| error_desc || String || The technical error message (always English) useful for debugging the problem. Might be the same as error message if there is no more information available<br />
|-<br />
| code || String || Error code consisting of an upper-case module identifier and a four-digit message number, separated by a dash; e.g. "MSG-0012"<br />
|-<br />
| error_stack || Array || If configured (see "com.openexchange.ajax.response.includeStackTraceOnError" in 'server.properties') this field provides the stack trace of associated Java exception represented as a JSON array<br />
|-<br />
| categories || String OR Array || Either a single (String) or list (Array) of upper-case category identifiers to which the error belongs. E.g.<br />
{| cellspacing="0" border="1"<br />
| "USER_INPUT" || An error resulting from wrong or missing input from front-end (e.g. mandatory field missing).<br />
|-<br />
| "CONFIGURATION" || An error related to user/system configuration which denies requested operation.<br />
|-<br />
| "PERMISSION_DENIED" || An error related to insufficient permission settings.<br />
|-<br />
| "TRY_AGAIN" || A requested operation could not be accomplished because a needed resource is temporary down or missing (e.g. imap server rejects connection because of too many established connections).<br />
|-<br />
| "SERVICE_DOWN" || A subsystem or third party service is down and therefore does not respond (e.g. database is down).<br />
|-<br />
| "CONNECTIVITY" || The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.<br />
|-<br />
| "ERROR" || A programming error which was caused by incorrect program code.<br />
|-<br />
| "CONFLICT" || A concurrent modification.<br />
|-<br />
| "CAPACITY" || The requested operation could not be performed cause an underlying resource is full or busy (e.g. IMAP folder exceeds quota).<br />
|-<br />
| "TRUNCATED" || The given data could not be stored into the database because an attribute contains a too long value.<br />
|-<br />
| "WARNING" || Action was at least partially successful, but a condition occurred that merited a warning<br />
|}<br />
|-<br />
| category || Number || Maintained for legacy reasons: The numeric representation of the first category:<br />
{| cellspacing="0" border="1"<br />
| 1 || An error resulting from wrong or missing input from front-end (e.g. mandatory field missing).<br />
|-<br />
| 2 || An error strictly related to user configuration which denies requested operation.<br />
|-<br />
| 3 || An error related to insufficient permission settings.<br />
|-<br />
| 4 || A requested operation could not be accomplished because a needed resource is temporary down or missing (e.g. imap server rejects connection because of too many established connections).<br />
|-<br />
| 5 || A subsystem or third party service is down and therefore does not respond (e.g. database is down).<br />
|-<br />
| 6 || The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.<br />
|-<br />
| 8 || A programming error which was caused by incorrect programm code.<br />
|-<br />
| 9 || A concurrent modification.<br />
|-<br />
| 11 || The requested operation could not be performed cause an underlying resource is full or busy (e.g. IMAP folder exceeds quota).<br />
|-<br />
| 12 || The given data could not be stored into the database because an attribute contains a too long value.<br />
|-<br />
| 13 || Action was at least partially successful, but a condition occurred that merited a warning<br />
|}<br />
|}<br />
<br />
Data from the client to the server can be sent in several formats. Small amounts of data are sent as <code>application/x-www-urlencoded</code> in query parameters in the request URI. For POST requests, some or all parameters may be sent in the request body instead of in the URI using any valid encoding for POST requests. Alternatively, some requests specify that data is sent as <code>text/javascript</code> in the body of a PUT request. The format of the request body for PUT requests is the same as for sending data from the server to the client, except that the payload is sent directly, without being wrapped in another object.<br />
<br />
When updating existing data, the client sends only fields that were modified. To explicitly delete a field, the field is sent with the value <code>null</code>. For fields of type <code>String</code>, the empty string <code>""</code> is equivalent to <code>null</code>.<br />
<br />
=== Error handling ===<br />
<br />
If the session of the user times out, if the client doesn't send a session ID or if the session for the specified session ID can not be found then the server returns the above described response object, that contains an error code and an error message. If the request URI or the request body is malformed or incomplete then the server returns the reponse object with an error message, too. In case of internal server errors, especially Java exceptions, or if the server is down, it returns the HTTP status code 503, Service Unavailable. Other severe errors may return other HTTP status values.<br />
<br />
Application errors, which can be caused by a user and are therefore expected during the operation of the groupware, are reported by setting the field error in the returned object, as described in [[#ResponseBody | Response body]]. Since the error messages are translated by the client, they can not be composed of multiple variable parts. Instead, the error message can contain simplified printf()-style conversion specifications, which are replaced by elements from the array in the field error_params. If error_params is not present, no replacement occurs, even if parts of the error message match the syntax of a conversion specification.<br />
<br />
A simplified conversion specification, as used for error messages, is either of the form %s or %''n''$s, where ''n'' is a 1-based decimal parameter index. The conversion specifications are replaced from left to right by elements from error_params, starting at the first element. %s is replaced by the current element and the current index is incremented. %''n''$s is replaced by the ''n''th element and the current index is set to the (''n'' + 1)th element.<br />
<br />
Some error message contain data sizes which must be expressed in Bytes or Kilobytes etc., depending on the actual value. Since the unit must be translated, this conversion is performed by the client. Unfortunately, standard printf()-style formatting does not have a specifier for this kind of translation. Therefore, the conversion specification for sizes is the same as for normal strings, and the client has to determine which parameters to translate based on the error code. The current error codes and the corresponding size parameters are listed in [[#DataSizeParameters | Data size parameters]]<br />
<br />
{| id="DataSizeParameters" cellspacing="0" border="1"<br />
|+ align="bottom" | Data size parameters<br />
! Error code !! Parameter indices<br />
|-<br />
| AJP-0006 || 1<br />
|-<br />
| AJP-0020 || 1, 2<br />
|-<br />
| CON-0101 || 2, 3<br />
|-<br />
| FLS-0003 || 1, 2, 3<br />
|-<br />
| MSG-0065 || 1, 3<br />
|-<br />
| MSG-0066 || 1<br />
|-<br />
| NON-0005 || 1, 2<br />
|-<br />
|}<br />
<br />
<br />
=== Date and time ===<br />
<br />
Dates without time are transmitted as the number of milliseconds between 00:00 UTC on that date and 1970-01-01 00:00 UTC. Leap seconds are ignored, therefore this number is always an integer multiple of 8.64e7.<br />
<br />
Because ECMAScript Date objects have no way to explicitly specify a timezone for calculations, timezone correction must be performed on the server. Dates with time are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC (again, ignoring leap seconds) plus the offset between the ''user's'' timezone and UTC at the time in question. (See the Java method java.util.TimeZone.getOffset(long)). Unless optional URL parameter <code>'''timezone'''</code> is present. Then dates with time are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC (again, ignoring leap seconds) plus the offset between the ''specified'' timezone and UTC at the time in question.<br />
<br />
For some date and time values, especially timestamps, monotonicity is more important than the actual value. Such values are transmitted as the number of milliseconds since 1970-01-01 00:00 UTC, ignoring leap seconds and without timezone correction. If possible, a unique strictly monotonic increasing value should be used instead, as it avoids some race conditions described below.<br />
<br />
This specification refers to these three interpretations of the type Number as separate data types. The types are described in [[#DateAndTimeTypes | Date and time types]].<br />
<br />
{| id="DateAndTimeTypes" cellspacing="0" border="1"<br />
|+ align="bottom" | Date and time types<br />
! Type !! Time !! Timezone !! Comment<br />
|-<br />
| Date || No || UTC || Date without time.<br />
|-<br />
| Time || Yes || User || Date and time.<br />
|-<br />
| Timestamp || Yes || UTC || Timestamp or unique sequence number.<br />
|-<br />
|}<br />
<br />
=== Updates ===<br />
<br />
To allow efficient synchronization of a client with changes made by other clients and to detect conflicts, the server stores a timestamp of the last modification for each object. Whenever the server transmits data objects to the client, the response object described in [[#ResponseBody | Response body]] includes the field timestamp. This field contains a timestamp value which is computed as the maximum of the timestamps of all transmitted objects.<br />
<br />
When requesting updates to a previously retrieved set of objects, the client sends the last timestamp which belongs to that set of objects. The response contains all updates with timestamps greater than the one specified by the client. The field timestamp of the response contains the new maximum timestamp value.<br />
<br />
If multiple different objects may have the same timestamp values, then a race condition exists when an update is processed between two such objects being modified. The first, already modified object will be included in the update response and its timestamp will be the maximum timestamp value sent in the timestamp field of the response. If the second object is modified later but gets the same timestamp, the client will never see the update to that object because the next update request from the client supplies the same timestamp value, but only modifications with greater timestamp values are returned.<br />
<br />
If unique sequence numbers can't be used as timestamps, then the risk of the race condition can be at least minimized by storing timestamps in the most precise format and/or limiting update results to changes with timestamp values which are measurably smaller than the current timestamp value.<br />
<br />
=== Editing ===<br />
<br />
Editing objects is performed one object at a time. There may be multiple objects being edited by the same client simulataneously, but this is achieved by repeating the steps required for editing a single object. There is no batch edit or upload command.<br />
<br />
To edit an object, a client first requests the entire object from the server. The server response contains the timestamp field described in the previous section. For in-place editing inside a view of multiple objects, where only already retrieved fields can be changed, retrieving the entire object is not necessary, and the last timestamp of the view is used as the timestamp of each object in it.<br />
<br />
When sending the modified object back to the server, only modified fields need to be included in the sent object. The request also includes the timestamp of the edited object. The timestamp is used by the server to ensure that the object was not edited by another client in the meantime. If the current timestamp of the object is greater than the timestamp supplied by the client, then a conflict is detected and the field error is set in the response. Otherwise, the object gets a new timestamp and the response to the client is empty.<br />
<br />
If the client displays the edited object in a view together with other objects, then the client will need to perform an update of that view immediately after successfully uploading an edited object.<br />
<br />
=== File uploads ===<br />
<br />
File uploads are made by sending a POST request that submits both the file and the needed fields as parts of a request of content-type “multipart/form-data” or “multipart/mixed”. The file metadata are stored in a form field “file” (much like an <input type=”file” name=”file” /> would do). In general a call that allows file uploads via POST will have a corresponding call using PUT to send object data. The JSON-encoded object-data that is send as the body of a corresponding PUT call is, when performed as a POST with file uploads, put into the request parameter “json”.<br />
<br />
Since the upload is performed directly by the browser and is not an Ajax call, the normal callback mechanism for asynchronous Javascript calls cannot be used to obtain the result. For this reason the server responds to these POST calls with a complete HTML page that performs the callback and should not be displayed to the user. The HTML response is functionally equivalent to:<br />
<br />
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><br />
<html><br />
<head><br />
<META http-equiv="Content-Type" content=\"text/html; charset=UTF-8\"><br />
<script type="text/javascript"><br />
(parent["callback_<b>action</b>"] || window.opener && window.opener["callback_<b>action</b>"])<br />
(<b>{json}</b>)<br />
</script><br />
</head><br />
</html><br />
<br />
The placeholders <code>{json}</code> is replaced by the response with the timestamp that would be expected from the corresponding PUT method. The placeholder <code>action</code> is replaced by the value of the parameter <code>action</code> of the request (except for the import bundle, which is named "import" instead of the action name for legacy purposes). The content-type of the answer is <code>text/html</code>.<br />
<br />
Non-browser clients don't need to interpret HTML or JavaScript. The JSON data can be recognized by the outermost <code>({</code> and <code>})</code>, where the inner braces are part of the JSON value. For example, the regular expression <code>\((\{.*\})\)</code> captures the entire JSON value in its first capturing group.<br />
<br />
=== Documentation conventions ===<br />
<br />
The rest of this document describes all available requests for each module. A module usually supports several different requests, which are differentiated by the used HTTP method, URI path and supplied URI parameters. The description of each method generally contains the following elements:<br />
* the HTTP method followed by the request URI, inclusing the URI parameter action, which is used to differentiate methods,<br />
* a list of URI parameters which can or must be supplied by the client,<br />
* for PUT requests, content of the request body,<br />
* "Response with timestamp:"if the timestamp field is required in the response body or simply "Response:" if not,<br />
* content of the response payload, unless it is supposed to be empty.<br />
<br />
=== Common object data ===<br />
<br />
This table contains common fields which apply for any module's data type and is referenced throughout this document whenever a module's data type is described.<br />
<br />
{| id="CommonObjectData" cellspacing="0" border="1"<br />
|+ align="bottom" | Common object data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 1 || id || String || Object ID<br />
|-<br />
| 2 || created_by || String || User ID of the user who created this object.<br />
|-<br />
| 3 || modified_by || String || User ID of the user who last modified this object.<br />
|-<br />
| 4 || creation_date || Time || Date and time of creation.<br />
|-<br />
| 5 || last_modified || Time || Date and time of the last modification.<br />
|-<br />
| 20 || folder_id || String || Object ID of the parent folder.<br />
|-<br />
| 100 || categories || String || String containing comma separated the categories. Order is preserved. Changing the order counts as modification of the object. Not present in folder objects.<br />
|-<br />
| 101 || private_flag || Boolean || Overrides folder permissions in shared private folders: When true, this object is not visible to anyone except the owner. Not present in folder objects.<br />
|-<br />
| 102 || color_label || Number || Color number used by Outlook to label the object. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers between 0 and 10 (inclusive). Not present in folder objects.<br />
|-<br />
| 104 || number_of_attachments || Number || Number of attachments <br />
|-<br />
| 105 || lastModifiedOfNewestAttachmentUTC || Time || Date and time of the newest attachment written with UTC time zone.<br />
|}<br />
<br />
== Module "login" ==<br />
<br />
The login module is used to obtain a session from the user's login credentials. To understand the details of the different login methods, see the article titled "[[Login variations]]".<br />
<br />
=== Login ===<br />
<br />
POST <code>/ajax/login?action=login</code><br />
<br />
Parameters:<br />
* <code>name</code> – The login name.<br />
* <code>password</code> – The password.<br />
* <code>authId</code> (optional) – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.<br />
* <code>client</code> (optional) – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange.<br />
* <code>version</code> (optional) – Used version of the HTTP/JSON interface client.<br />
* <code>clientIP</code> (optional) – IP address of the client host for that the session is created. If this parameter is not specified the IP address of the HTTP client doing this request is used.<br />
* <code>clientUserAgent</code> (optional) – Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used.<br />
<br />
Response: A JSON object containing the session ID used for all subsequent requests. Additionally a random token is contained to be used for the Easy Login method.<br />
<br />
=== Form Login (since 6.20) ===<br />
<br />
POST <code>/ajax/login?action=formlogin</code><br />
<br />
This request implements a possible login to the web frontend by only using a simple HTML form. An example for such a form can be found in the backend's documentation folder (<code>/usr/share/doc/open-xchange-core</code>) under <code>examples/login.html</code>.<br />
<br />
Parameters:<br />
* <code>login</code> – The login name.<br />
* <code>password</code> – The password.<br />
* <code>authId</code> – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.<br />
* <code>client</code> – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange. If the autologin request should work the client must be the same as the client sent by the UI in the normal login request.<br />
* <code>version</code> – Used version of the HTTP/JSON interface client.<br />
* <code>autologin</code> – True or false. True tells the UI to issue a store request for the session cookie. This store request is necessary if you want the autologin request not to fail.<br />
* <code>uiWebPath</code> (optional) – Defines another path on the web server where the UI is located. If this parameter is not defined the configured default of the backend is used.<br />
* <code>clientIP</code> (optional) – IP address of the client host for that the session is created. If this parameter is not specified the IP address of the HTTP client doing this request is used.<br />
* <code>clientUserAgent</code> (optional) – Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used.<br />
<br />
Response: A redirect to the web UI. The URL of the web UI is either taken from the given parameter or from the configured default of the backend.<br />
<br />
For a complete description of the FormLogin-Process please see [[FormLogin|this documentation]]<br />
<br />
=== Token Login (since 7.0.1) ===<br />
<br />
POST <code>/ajax/login?action=tokenLogin</code><br />
<br />
This request allows every possible client to create a very short living session. This session can then be transferred to any other client preferably a browser entering then the normal web interface. Then the sessions life time will be extended equally to every other session.<br />
<br />
Compared to the login mechanism using the random token, this request is more secure because two tokens are used. One of these tokens is only known to the client and one is generated by the server. Only the combination of both tokens allows to use the session. The combination of both tokens must be done by the client creating the session.<br />
<br />
Parameters:<br />
* <code>login</code> – The login information.<br />
* <code>password</code> – The password.<br />
* <code>clientToken</code> – Client side identifier for accessing the session later. The value should be some token that is unique for every login request.<br />
* <code>authId</code> – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request.<br />
* <code>client</code> – Identifier of the client using the HTTP/JSON interface. This is for statistic evaluations what clients are used with Open-Xchange. If the autologin request should work the client should be the same as the client sent by the UI in the normal login request. For security considerations it can become necessary to define here the correct client that will use the session.<br />
* <code>version</code> – Version of the HTTP/JSON interface client. Only for statistic evaluations.<br />
* <code>autologin</code> – True or false. True tells the UI to issue a store request for the session cookie. This store request is necessary if you want the autologin request not to fail. This must be enabled on the server and a client can test with the autologin request if it is enabled or not.<br />
* <code>uiWebPath</code> (optional) – Defines another path on the web server where the UI is located. If this parameter is not defined the configured default of the backend is used.<br />
* <code>clientIP</code> (optional) – IP address of the client host for that the session is created. If this parameter is not specified the IP address of the HTTP client doing this request is used. Currently the IP address may change when using the session with both tokens. This can be disabled in future releases for security considerations.<br />
* <code>clientUserAgent</code> (optional) – Value of the User-Agent header of the client host for that the session is created. If this parameter is not specified the User-Agent of the current HTTP client doing this request is used. Currently the User-Agent may change when using the session. This can be disabled in future releases for security considerations.<br />
<br />
<br />
Response: A redirect to the web UI. The URL of the web UI is either taken from the given parameter or from the configured default of the backend. This redirect will only contain the server side token. The client side token sent in the request must be appended by the client creating the session. The final URL must have the form <code style="white-space: nowrap"><var>redirect_URL</var>&amp;clientToken=<var>token</var></code>. Both tokens are necessary to use the session and both tokens must match. Otherwise the session is terminated.<br />
<br />
=== Tokens (since 7.0.1) ===<br />
<br />
POST <code>/ajax/login?action=tokens</code><br />
<br />
This request allows clients to access a session created with the [[#Token_Login_.28since_7.0.1.29 | tokenLogin]] request. When accessing the session its life time is extended equally to every other session.<br />
<br />
Parameters:<br />
* <code>serverToken</code> – Server side identifier for accessing the session. This identifier was created by the server and is contained in the tokenLogin response.<br />
* <code>clientToken</code> – Client side identifier for accessing the session. This identifier was created by the client and passed within the POST data of the tokenLogin request.<br />
* <code>client</code> – Identifier of the client using the HTTP/JSON interface. Currently this request allows to change the client identifier for the session. This eases creating the session because the identifier of the client using the session must not be known. For security considerations it can become necessary to drop this parameter.<br />
<br />
<br />
Response: A JSON object conform to the normal [[#ResponseBody | response body]] contrary to the JSON object of the normal login request. This JSON object contains the session identifier, the login, the identifier and the locale of the user.<br />
<br />
=== Logout ===<br />
<br />
GET <code>/ajax/login?action=logout</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
=== Refresh secret cookie (since 6.18.2) ===<br />
<br />
GET <code>/ajax/login?action=refreshSecret</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
=== Refresh auto-login cookie ===<br />
<br />
GET <code>/ajax/login?action=store</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
=== Redirect ===<br />
<br />
GET <code>/ajax/login;jsessionid=1157370816112.OX1?action=redirect</code><br />
<br />
'''SECURITY WARNING!''' Utilizing this request is '''INSECURE'''! This request allows to access a session with a single one time token. This one time token may be delivered to the wrong client if the AJP protocol has an error or Apache or the load balancer make a mistake. This will cause a wrong user to be in a wrong session. '''IMMEDIATELY''' consider not to use this request anymore. You have been warned. Use instead the FormLogin that does not need to use the redirect request.<br />
<br />
Parameters:<br />
* <code>random</code> – A session random token to jump into the session. This random token is part of the login response. Only a very short configurable time after the login it is allowed to jump into the session with the random token.<br />
* <code>client</code> (optional) – The client can be defined here newly if it is not correct on the login request itself.<br />
* <code>store</code> (optional) – Tells the UI to do a store request after login to be able to use autologin request.<br />
* <code>uiWebPath</code> (optional) – The optional path on the webserver to the UI. If this parameter is not given the configured uiWebPath is used.<br />
<br />
=== Change IP ===<br />
<br />
The following request is especially for integration with systems located in the providers infrastructure. If those systems create a session with the following request the client host IP address in the session can be changed. The IP check for following requests will be done using this newly set client host IP address.<br />
<br />
POST <code>/ajax/login?action=changeip</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>clientIP</code> – New IP address of the client host for the current session.<br />
<br />
Response: A JSON object containing the string "1" as data attribute.<br />
<br />
=== Redeem Token (since 7.4.0)===<br />
<br />
POST <code>/ajax/login?action=redeemToken</code><br />
<br />
Parameters:<br />
* <code>token</code> – The token created with [[#Get_a_login_token | acquireToken]].<br />
* <code>authId</code> – Identifier for tracing every single login request passed between different systems in a cluster. The value should be some token that is unique for every login request. This parameter must be given as URL parameter and not inside the body of the POST request. <br />
* <code>client</code> – Identifier of the client using the HTTP/JSON interface. The client must identifier must be the same for each request after creating the login session. <br />
* <code>secret</code> – The value of the secret string for token logins. This is configured through the tokenlogin-secrets configuration file.<br />
<br />
Response: A JSON object containing the session ID used for all subsequent requests. Additionally a random token is contained to be used for the Easy Login method. If configured within tokenlogin-secrets configuration file even the user password will be returned.<br />
<br />
== Module "config" ==<br />
<br />
The config module is used to retrieve and set user-specific configuration. The configuration is stored in a tree. Each node of the tree has a name and a value. The values of leaf nodes are strings which store the actual configuration data. The values of inner nodes are defined recursively as objects with one field for each child node. The name and the value of each field is the name and the value of the corresponding child node, respectively.<br />
<br />
The namespace looks like the following:<br />
<br />
* <code>/ajax/config/</code><br />
** <code>gui</code> – A string containing GUI-specific settings (currently, it is a huge [[#Low_level_protocol | JSON]] object).<br />
** <code>fastgui</code> - A string containing GUI-specific settings. This is a JSON object that must be kept small for performance.<br />
** <code>context_id</code> - the unique identifier of the context (read-only, added 2008-01-28).<br />
** <code>cookielifetime</code> - the cookie life time in seconds or <code>-1</code> for session cookie (read-only, added 2010-11-16).<br />
** <code>identifier</code> – the unique identifier of the user (read-only).<br />
** <code>contact_id</code> – the unique identifier of the contact data of the user (read-only).<br />
** <code>language</code> – the configured language of the user.<br />
** <code>timezone</code> – the configured timezone of the user.<br />
** <code>availableTimeZones</code> – a JSON object containing all available time zones. The key is the time zone identifier and the value contains its name in users language. (read-only, added 2010-07-08/v6.18).<br />
** <code>calendarnotification</code> - send a mail notification for appointments (deprecated since 2008-12-11)<br />
** <code>tasknotification</code> - send a mail notification for tasks (deprecated since 2008-12-11)<br />
** <code>reloadTimes</code> - Selectable times for GUI reload<br />
** <code>serverVersion</code> - Version string of the server.<br />
** <code>currentTime</code> - User timezone specific long of the current server time.<br />
** <code>maxUploadIdleTimeout</code> - Timeout after that idle uploads are deleted.<br />
** <code>folder/</code> – the standard folder of the user<br />
*** <code>tasks</code> – the standard task folder (read-only)<br />
*** <code>calendar</code> – the standard calendar folder (read-only)<br />
*** <code>contacts</code> – the standard contacts folder (read-only)<br />
*** <code>infostore</code> – the private infostore folder (read-only, since v6.20.1)<br />
*** <code>eas</code> – whether EAS folder selection is enabled (read-only)<br />
** <code>mail/</code> – settings for the email module (deprecated 2008-04-29)<br />
*** <code>addresses</code> – all email addresses of the user including the primary address (read-only, deprecated 2008-04-29)<br />
*** <code>defaultaddress</code> – primary email address of the user (read-only, deprecated 2008-04-29)<br />
*** <code>sendaddress</code> – one email address out of the addresses list that are email sent with. (deprecated 2008-04-29)<br />
*** <code>folder/</code> – the standard email folders (read-only, deprecated 2008-04-29)<br />
**** <code>inbox</code> – identifier of the folder that gets all incoming mails (read-only, deprecated 2008-04-29)<br />
**** <code>drafts</code> – identifier of the folder with the mail drafts (read-only, deprecated 2008-04-29)<br />
**** <code>trash</code> – identifier of the folder with the deleted mails (read-only, deprecated 2008-04-29)<br />
**** <code>spam</code> – identifier of the folder with the spam mails (read-only, deprecated 2008-04-29)<br />
**** <code>sent</code> – identifier of the folder with the sent mails (read-only, deprecated 2008-04-29)<br />
*** <code>htmlinline</code> – activate inlining of HTML attachments. (deprecated 2008-04-29)<br />
*** <code>colorquote</code> – color quoted lines. (deprecated 2008-04-29)<br />
*** <code>emoticons</code> – display emoticons as graphics. (deprecated 2008-04-29)<br />
*** <code>harddelete</code> – delete emails at once. (deprecated 2008-04-29)<br />
*** <code>inlineforward</code> – forward messages as inline or attachment. (deprecated 2008-04-29)<br />
*** <code>vcard</code> – attach vcard when sending mails. (deprecated 2008-04-29)<br />
*** <code>notifyonreadack</code> – notify on read acknowledgement. (deprecated 2008-04-29)<br />
*** <code>msgpreview</code> – show a message preview. (deprecated 2008-04-29)<br />
*** <code>ignorereplytext</code> (deprecated 2008-04-29)<br />
*** <code>nocopytosent</code> – don't put a copy to the sent folder when sending mails. (deprecated 2008-04-29)<br />
*** <code>spambutton</code> - Spam Button should be displayed in GUI or not. (deprecated 2008-04-29)<br />
** <code>participants</code><br />
*** <code>autoSearch</code> - If a search for all users, groups and resources when participant selection dialog is opened. (read-only, added 2008-10-09/SP5)<br />
*** <code>maximumNumberParticipants</code> – Defines the maximum number of participants for appointments and tasks. (read-only, added 2008-10-20/SP5)<br />
*** <code>showWithoutEmail</code> - If external participants without email should be shown.<br />
*** <code>showDialog</code> – Enables participant selection dialog for appointments and tasks. (read-only, added 2008-04-30/SP4)<br />
** <code>availableModules</code> – Contains a JSON array listing all enabled modules for a user. GUI loads Plugins through this list. To get your plugin listed here, create a subtree below <code>modules/</code> without a <code>module</code> subelement or with a subelement containing <code>true</code> (read-only, added 2008-02-25)<br />
** <code>minimumSearchCharacters</code> – Minimum number of characters a search pattern must have to prevent large responses and slow queries. (read-only, added 2008-10-20/SP5)<br />
** <code>modules</code><br />
*** <code>portal</code><br />
**** <code>gui</code> GUI settings for portal module<br />
**** <code>module</code><br />
*** <code>mail</code><br />
**** <code>addresses</code> – all email addresses of the user including the primary address (read-only, added 2008-02-25)<br />
**** <code>appendmailtext</code> – (added 2008-02-25)<br />
**** <code>allowhtmlimages</code> – Alters default setting whether external images contained in HTML content are allowed or not (added 2008-05-27)<br />
**** <code>colorquoted</code> – color quoted lines (added 2008-02-25)<br />
**** <code>contactCollectFolder</code> – contact folder id to save mail addresses from sent mails (added 2008-10-16)<br />
**** <code>contactCollectEnabled</code> – switch contact collection on/off (added 2008-10-16)<br />
**** <code>contactCollectOnMailAccess</code> – enables/disables contact collection for incoming mails. Default is true. (added 2009-09-24)<br />
**** <code>contactCollectOnMailTransport</code> – enables/disables contact collection for outgoing mails. Default is true. (added 2009-09-24)<br />
**** <code>defaultaddress</code> – primary email address of the user (read-only, added 2008-02-25)<br />
**** <code>deletemail</code> – delete emails or move to trash (added 2008-02-25)<br />
**** <code>emoticons</code> – display emoticons as graphics (added 2008-02-25)<br />
**** <code>defaultFolder</code><br />
***** <code>drafts</code> – identifier of the folder with the mail drafts (read-only, added 2008-02-25)<br />
***** <code>inbox</code> – identifier of the folder that gets all incoming mails (read-only, added 2008-02-25)<br />
***** <code>sent</code> – identifier of the folder with the sent mails (read-only, added 2008-02-25)<br />
***** <code>spam</code> – identifier of the folder with the spam mails (read-only, added 2008-02-25)<br />
***** <code>trash</code> – identifier of the folder with the deleted mails (read-only, added 2008-02-25)<br />
**** <code>forwardmessage</code> – forward messages as inline or attachment (added 2008-02-25)<br />
**** <code>gui</code> GUI settings for mail module<br />
**** <code>inlineattachments</code> – activate inlining of HTML attachments (added 2008-02-25)<br />
**** <code>linewrap</code> – (added 2008-02-25)<br />
**** <code>module</code> – if mail module is enabled or not (added 2008-02-25)<br />
**** <code>phishingheaders</code> – header(s) identifying phishing headers (added 2008-05-27)<br />
**** <code>replyallcc</code> – put all recipients on reply all into CC (added 2008-12-16/SP5)<br />
**** <code>sendaddress</code> – one email address out of the addresses list that are email sent with (added 2008-02-25)<br />
**** <code>spambutton</code> – Spam Button should be displayed in GUI or not (added 2008-02-25)<br />
**** <code>vcard</code> – attach vcard when sending mails (added 2008-02-25)<br />
*** <code>calendar</code><br />
**** <code>calendar_conflict</code><br />
**** <code>calendar_freebusy</code><br />
**** <code>calendar_teamview</code><br />
**** <code>gui</code> GUI settings for the calendar module<br />
**** <code>module</code><br />
**** <code>notifyNewModifiedDeleted</code> receive mail notification for new, modified or deleted appointments (added 2008-12-11/SP5)<br />
**** <code>notifyAcceptedDeclinedAsCreator</code> receive mail notification for accepted or declined appointments created by the user (added 2008-12-11/SP5)<br />
**** <code>notifyAcceptedDeclinedAsParticipant</code> receive mail notification for accepted or declined appointments that the user participates (added 2008-12-11/SP5)<br />
**** <code>defaultStatusPrivate</code> Default status for new appointments in private folders, where the user is participant. This does not affect appointments created by this user, which always have the status "accepted". The status are described in [[#UserParticipantObject | User participant object]]. Default is 0:none (added 2009-07-20/6.12)<br />
**** <code>defaultStatusPublic</code> Default status for new appointments in public folders, where the user is participant. This does not affect appointments created by this user, which always have the status "accepted". The status are described in [[#UserParticipantObject | User participant object]]. Default is 0:none (added 2009-07-20/6.12)<br />
*** <code>contacts</code><br />
**** <code>gui</code> GUI settings for the contacts module<br />
**** <code>mailAddressAutoSearch</code> – Define if a search is triggered when the recipient selection dialog is opened or the folder is changed. (read-only, added 2008-10-20/SP5)<br />
**** <code>module</code> True if the contact module is enabled for the current user, false otherwise.<br />
**** <code>singleFolderSearch</code> – True if the current user is allowed to search for contacts only in a single folder. False if contact searches across all folders are allowed. (read-only, added 2009-02-04/SP5 U1)<br />
**** <code>characterSearch</code> – True if the side bar for searching for contacts by a start letter should be displayed. False if the side bar should be hidden. (read-only, added 2009-05-29/6.10)<br />
**** <code>allFoldersForAutoComplete</code> – true if an auto complete search may omit the folder identifier array and search for contacts in all readable folders. This is configured through the contact.properties configuration file. (read-only, added 2010-07-22/v6.18.0)<br />
*** <code>tasks</code><br />
**** <code>gui</code> GUI settings for the tasks module<br />
**** <code>module</code><br />
**** <code>delegate_tasks</code><br />
**** <code>notifyNewModifiedDeleted</code> receive mail notification for new, modified or deleted tasks (added 2008-12-11/SP5)<br />
**** <code>notifyAcceptedDeclinedAsCreator</code> receive mail notification for accepted or declined tasks created by the user (added 2008-12-11/SP5)<br />
**** <code>notifyAcceptedDeclinedAsParticipant</code> receive mail notification for accepted or declined taks that the user participates (added 2008-12-11/SP5)<br />
*** <code>infostore</code><br />
**** <code>gui</code> GUI settings for the infostore module<br />
**** <code>folder</code> – the standard infostore folders (read-only, since 7.6.0)<br />
***** <code>trash</code> – identifier of the default infostore trash folder (read-only, since 7.6.0)<br />
**** <code>module</code><br />
*** <code>interfaces</code><br />
**** <code>ical</code><br />
**** <code>vcard</code><br />
**** <code>syncml</code><br />
*** <code>folder</code><br />
**** <code>gui</code> UI settings for the folder tree<br />
**** <code>public_folders</code><br />
**** <code>read_create_shared_folders</code><br />
**** <code>tree</code> – Selected folder tree, the user wants to use. Currents trees are 0 for the known OX folder tree and 1 for the new virtual folder tree. (added 2010-04-09/6.18)<br />
*** <code>com.openexchange.extras</code><br />
**** <code>module</code> – Extras link in the configuration (read only, added 2008-04-29)<br />
*** <code>com.openexchange.user.passwordchange</code><br />
**** <code>module</code> – Will load Plug-In which allows to change the Password within the users configuration (read only, added 2008-07-09)<br />
*** <code>com.openexchange.user.personaldata</code><br />
**** <code>module</code> – Will load Plug-In which allows to edit personal contact information within the users configuration (read only, added 2008-07-09)<br />
*** <code>com.openexchange.group</code><br />
**** <code>enabled</code> – Specifies whether the user is allowed to edit groups and loads the corresponding Plug-In. (read only, added 2008-08-08)<br />
*** <code>com.openexchange.resource</code><br />
**** <code>enabled</code> – Specifies whether the user is allowed to edit resources and loads the corresponding Plug-In. (read only, added 2008-08-08)<br />
*** <code>com.openexchange.publish</code><br />
**** <code>enabled</code> – Specifies whether the user is allowed to publish items. (read only, added 2009-05-27)<br />
*** <code>com.openexchange.subscribe</code><br />
**** <code>enabled</code> – Specifies whether the user is allowed to subscribe sources. (read only, added 2009-05-27)<br />
*** <code>olox20</code><br />
**** <code>active</code> – Tells the UI if the user is allowed to use the OXtender for Microsoft Outlook 2. (read only, added 2011-03-15/6.20)<br />
**** <code>module</code> – Is set to false to prevent the UI from trying to load a plugin. (read only, added 2011-03-15/6.20)<br />
***<code>com.openexchange.oxupdater</code><br />
****<code>module</code> – Is true if the OXUpdater package is installed and started. (read only, added 2011-06-01/6.20)<br />
****<code>active</code> – Is true if the user is allowed to download the OXUpdater. Otherwise it's false. (read only, added 2011-06-01/6.20)<br />
***<code>com.openexchange.passwordchange</code><br />
**** <code>showStrength</code> – Show a widget, which displays the current passwort Strength while entering. (default: false)<br />
**** <code>minLength</code> – The minimum length of an entered password. (default: 4)<br />
**** <code>maxLength</code> – The maximum length of an entered password. 0 for unlimited. (default: 0)<br />
**** <code>regexp</code> – Defines the class of allowed special characters as Regular Expression. (default: [^a-z0-9])<br />
**** <code>special</code> – Shows an example of allowed special characters to the user. Should be a subset of "regexp" in a human readable format. (default: $, _, or %) <br />
<br />
=== Get configuration data ===<br />
<br />
GET <code>/ajax/config/path</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: Value of the node specified by path.<br />
<br />
=== Set configuration data ===<br />
<br />
PUT <code>/ajax/config/path</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The new value of the node specified by path.<br />
<br />
== Module "folders" ==<br />
<br />
The folders module is used to access the OX folder structure.<br />
<br />
=== Special System Folders ===<br />
<br />
Folders with some kind of special.<br />
<br />
{| cellspacing="0" border="1"<br />
! ID !! Type !! Description<br />
|-<br />
| 6 || contacts || System Users<br />
|}<br />
<br />
=== Get root folders ===<br />
<br />
GET <code>/ajax/folders?action=root</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
<br />
Response: An array with data for all folders at the root level of the folder structure. Each array element describes one folder and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
{| id="CommonFolderData" cellspacing="0" border="1"<br />
|+ align="bottom" | Common folder data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 1 || id || String || Object ID<br />
|-<br />
| 2 || created_by || String || User ID of the user who created this object.<br />
|-<br />
| 3 || modified_by || String || User ID of the user who last modified this object.<br />
|-<br />
| 4 || creation_date || Time || Date and time of creation.<br />
|-<br />
| 5 || last_modified || Time || Date and time of the last modification.<br />
|-<br />
| 6 || last_modified_utc || Timestamp || Timestamp of the last modification. Note that the type is Timestamp, not Time. See [[#Date and time]] for details. (added 2008-10-17, with SP5, temporary workaround)<br />
|-<br />
| 20 || folder_id || String || Object ID of the parent folder.<br />
|}<br />
<br />
{| id="DetailedFolderData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed folder data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 300 || title || String || Name of this folder.<br />
|-<br />
| 301 || module || String || Name of the module which implements this folder; e.g. "tasks", "calendar", "contacts", "infostore", or "mail"<br />
|-<br />
| 302 || type || Number || Type of folder:<br />
{| cellspacing="0" border="1"<br />
| 1 || private<br />
|-<br />
| 2 || public<br />
|-<br />
| 3 || shared<br />
|-<br />
| 5 || system folder<br />
|-<br />
| 16 || trash<br />
|}<br />
|-<br />
| 304 || subfolders || Boolean || true if this folder has subfolders.<br />
|-<br />
| 305 || own_rights || Number or String || Permissions which apply to the current user, as described either in [[#PermissionFlags | Permission flags]] or in RFC 2086.<br />
|-<br />
| 306 || permissions || Array || Each element is an object described in [[#PermissionObject | Permission object]].<br />
|-<br />
| 307 || summary || String || Information about contained objects.<br />
|-<br />
| 308 || standard_folder || Boolean || Indicates whether or not folder is marked as a default folder (only OX folder)<br />
|-<br />
| 309 || total || Number || The number of objects in this Folder.<br />
|-<br />
| 310 || new || Number || The number of new objects in this Folder.<br />
|-<br />
| 311 || unread || Number || The number of unread objects in this Folder.<br />
|-<br />
| 312 || deleted || Number || The number of deleted objects in this Folder.<br />
|-<br />
| 313 || capabilities || Number || Bit mask containing information about mail folder capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not.<br />
|-<br />
| 315 || subscr_subflds || Boolean || Indicates whether subfolders should appear in folder tree or not.<br />
|-<br />
| 316 || standard_folder_type || Number || Indicates the default folder type. Zero for non-default folder. See [[#DefaultTypes | Standard folder types]]<br />
|-<br />
| 317 || supported_capabilities || Array || Each element is a String identifying a supported folder capability as described in [[#SupportedCapabilities | supported capabilities]]. Only applicable for non-mail folders. Read Only, Since 7.4.0.<br />
|-<br />
| 3010 || com.openexchange.publish.publicationFlag || Boolean || Indicates whether this folder is published. Read Only, provided by the com.openexchange.publish plugin, since 6.14.<br />
|-<br />
| 3020 || com.openexchange.subscribe.subscriptionFlag || Boolean || Indicates whether this folder has subscriptions storing their content in this folder. Read Only, provided by the com.openexchange.subscribe plugin, since 6.14.<br />
|-<br />
| 3030 || com.openexchange.folderstorage.displayName || String || Provides the display of the folder's owner. Read Only, Since 6.20.<br />
|}<br />
<br />
<br />
<br />
<br />
{| id="PermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0-6 || Folder permissions:<br />
{| cellspacing="0" border="1"<br />
| 0 || No permissions.<br />
|-<br />
| 1 || See the folder.<br />
|-<br />
| 2 || Create objects in the folder. '''Note''': '''Does not apply to folders of module ''system'''''.<br />
|-<br />
| 4 || Create subfolders.<br />
|-<br />
| 64 || All permissions. This is currently the same as "Create subfolders" but in the future additional permissions may be added that will be given to the user when using this value.<br />
|}<br />
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.<br>'''NOTE''': ''Create objects in the folder'' is not covered by ''Create subfolders'' if folder's module is ''system''.<br />
|-<br />
| 7-13 || Read permissions for objects in the folder:<br />
{| cellspacing="0" border="1"<br />
| 0 || No permissions.<br />
|-<br />
| 1 || Read only own objects.<br />
|-<br />
| 2 || Read all objects.<br />
|-<br />
| 64 || All permissions. This is currently the same as "Read all objects" but in the future additional permissions may be added that will be given to the user when using this value.<br />
|}<br />
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.<br />
|-<br />
| 14-20 || Write permissions for objects in the folder:<br />
{| cellspacing="0" border="1"<br />
| 0 || No permissions.<br />
|-<br />
| 1 || Modify only own objects.<br />
|-<br />
| 2 || Modify all objects.<br />
|-<br />
| 64 || All permissions. This is currently the same as "Modify all objects" but in the future additional permissions may be added that will be given to the user when using this value.<br />
|}<br />
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.<br />
|-<br />
| 21-27 || Delete permissions for objects in the folder:<br />
{| cellspacing="0" border="1"<br />
| 0 || No permissions.<br />
|-<br />
| 1 || Delete only own objects.<br />
|-<br />
| 2 || Delete all objects.<br />
|-<br />
| 64 || All permissions. This is currently the same as "Delete all objects" but in the future additional permissions may be added that will be given to the user when using this value.<br />
|}<br />
The values are scalars and not bit sets. Any other than the described values should not be used. If they are used expect an exception from the backend. Every value automatically contains the access rights covered by lower values.<br />
|-<br />
| 28 || Admin flag:<br />
{| cellspacing="0" border="1"<br />
| 0 || No permissions.<br />
|-<br />
| 1 || Every operation modifying the folder in some way requires this permission. This are e.g. changing the folder name, modifying the permissions, deleting or moving the folder.<br />
|}<br />
|}<br />
<br />
{| id="PermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || For non-mail folders, a number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| rights || String || For mail folders, the rights string as defined in RFC 2086.<br />
|-<br />
| entity || Number || User ID of the user or group to which this permission applies.<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user.<br />
|}<br />
<br />
{| id="Capabilities" cellspacing="0" border="1"<br />
|+ align="bottom" | Capabilities<br />
! Bit !! Description<br />
|-<br />
| 0 || Mailing system supports permissions.<br />
|-<br />
| 1 || Mailing system supports ordering mails by their thread reference.<br />
|-<br />
| 2 || Mailing system supports quota restrictions.<br />
|-<br />
| 3 || Mailing system supports sorting.<br />
|-<br />
| 4 || Mailing system supports folder subscription.<br />
|}<br />
<br />
{| id="DefaultTypes" cellspacing="0" border="1"<br />
|+ align="bottom" | Standard Folder Types<br />
! Bit !! Description<br />
|-<br />
| 0 || No default folder.<br />
|-<br />
| 1 || Task.<br />
|-<br />
| 2 || Calendar.<br />
|-<br />
| 3 || Contact.<br />
|-<br />
| 7 || Inbox.<br />
|-<br />
| 8 || Infostore.<br />
|-<br />
| 9 || Drafts.<br />
|-<br />
| 10 || Sent.<br />
|-<br />
| 11 || Spam.<br />
|-<br />
| 12 || Trash.<br />
|}<br />
<br />
{| id="SupportedCapabilities" cellspacing="0" border="1"<br />
|+ align="bottom" | Supported Capabilities<br />
! Name !! Description<br />
|-<br />
| permissions || Folder storage supports permissions.<br />
|-<br />
| publication || Folder storage supports folder publication.<br />
|-<br />
| quota || Folder storage supports quota restrictions.<br />
|-<br />
| sort || Folder storage supports sorting.<br />
|-<br />
| subscription || Folder storage supports folder subscription.<br />
|}<br />
<br />
=== Get subfolders ===<br />
<br />
GET <code>/ajax/folders?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>parent</code> – Object ID of a folder, which is the parent folder of the requested folders.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].<br />
* <code>all</code> – Set to <code>1</code> to list even not subscribed folders.<br />
* <code>tree</code> – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
* <code>errorOnDuplicateName</code> – An optional flag to enable or disable (default) check for duplicate folder names within returned folder response (since v6.20.1). If a duplicate folder name is detected, an appropriate error is returned as [[#ResponseBody | response]].<br />
<br />
Response with timestamp: An array with data for all folders, which have the folder with the requested object ID as parent. Each array element describes one folder and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get path ===<br />
<br />
GET <code>/ajax/folders?action=path</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of a folder.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
<br />
Response with timestamp: An array with data for all parent nodes until root folder. Each array element describes one folder and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get updated folders ===<br />
<br />
GET <code>/ajax/folders?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>parent</code> – Object ID of a folder, which is the parent folder of the requested folders.<br />
* <code>timestamp</code> – Timestamp of the last update of the requested folders.<br />
* <code>ignore</code> (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
<br />
Response with timestamp: An array with data for new, modified and deleted folders. New and modified folders are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted folders (should the <code>ignore</code> parameter be ever implemented) would be identified by their object IDs as plain strings, without being part of a nested array.<br />
<br />
=== Get a folder ===<br />
<br />
GET <code>/ajax/folders?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested folder.<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
<br />
Response with timestamp: An object containing all data of the requested folder. The fields of the object are listed in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. The field id is not present. Since OX access controls are folder-based, the folder object also defines the permissions for the objects it contains. The permissions for a given user or group are defined by the object described in [[#PermissionObject | Permission object]]. The format of the actual permissions depends on the type of the folder. The permissions of mail folders are transmitted as a rights string as defined in section 3 of RFC 2086. Permissions of all other folders are transmitted as a single nonnegative integer number. The permissions for any given action on the folder or on contained objects is defined by a group of bits in the binary representation of this number. Each group of bits is interpreted as a separate number. Zero always means "no permissions". Any other values add new permissions and always include the permissions of all lower values. The individual values are described in [[#PermissionFlags | Permission flags]].<br />
<br />
=== Update a folder ===<br />
<br />
PUT <code>/ajax/folders?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the updated folder.<br />
* <code>timestamp</code> – Timestamp of the updated folder. If the folder was modified after the specified timestamp, then the update must fail.<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present.<br />
<br />
=== Create a folder ===<br />
<br />
PUT <code>/ajax/folders?action=new</code><br />
<br />
Parameters:<br />
* <code>folder_id</code> – The parent folder of the newly created folder<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. The field id should not be present.<br />
<br />
Provided that permission is granted to create a folder, its module is bound to the limitation, that the new folder's module must be equal to parent folder's module except that:<br />
* Parent folder is one of the system folders <code>private</code>, <code>public</code>, or <code>shared</code>. Below these folders task, calendar, and contact modules are permitted.<br />
* Parent folder's module is one of task, calendar, or contact. Below this kind of folders task, calendar, and contact modules are permitted.<br />
<br />
Response: Object ID of the newly created folder.<br />
<br />
=== Delete folders ===<br />
<br />
PUT <code>/ajax/folders?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted folders.<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered. <br />
* <code>hardDelete</code> - Optional, defaults to \"false\". If set to \"true\", the folders are deleted permanently. Otherwise, and if the underlying storage supports a trash folder and the folders are not yet located below the trash folder, they are moved to the trash folder.<br />
<br />
Request body: An array with object IDs of the folders that shall be deleted.<br />
<br />
Response: An array with object IDs of folders that were '''NOT''' deleted. There may be a lot of different causes for a not deleted folder: A folder has been modified in the mean time, the user does not have the permission to delete it or those permissions have just been removed, the folder does not exist, etc.<br />
<br />
=== Clearing a folder's content ===<br />
PUT <code>/ajax/folders?action=clear</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>tree</code> – (Preliminary) The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>allowed_modules</code> – (Preliminary) An array of modules (either numbers or strings; e.g. "tasks,calendar,contacts,mail") supported by requesting client. If missing, all available modules are considered.<br />
<br />
Request body: A JSON array containing the folder ID(s) whose content should be cleared. '''NOTE:''' Although the requests offers to clear multiple folders at once it is recommended to clear only one folder per request since if any exception occurs<br />
(e.g. missing permissions) the complete request is going to be aborted.<br />
<br />
Response: A JSON array containing the IDs of folders that could not be cleared due to a concurrent modification. Meaning you receive an empty JSON array if everything worked well.<br />
<br />
=== Get all visible folder of a certain module (since v6.18.2) ===<br />
PUT <code>/ajax/folders?action=allVisible</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>tree</code> – The identifier of the folder tree. If missing '0' (primary folder tree) is assumed.<br />
* <code>content_type</code> – The desired content type (either numbers or strings; e.g. "tasks", "calendar", "contacts", "mail")<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for folders are defined in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].<br />
<br />
Request body: None<br />
<br />
Response with timestamp: A JSON object containing three fields: "private", "public, and "shared". Each field is a JSON array with data for all folders. Each folder is itself described by an array.<br />
<br />
== Module "tasks" ==<br />
<br />
The tasks module is used to access task information.<br />
<br />
=== Get all tasks ===<br />
<br />
GET <code>/ajax/tasks?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for tasks are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Response with timestamp: An array with task data. Each array element describes one task and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
{| id="DetailedTaskAndAppointmentData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed task and appointment data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 200 || title || String || Short description.<br />
|-<br />
| 201 || start_date || Date or Time || Inclusive start of the event as Date for tasks and whole day appointments and Time for normal appointments. For sequencies, this date must be part of the sequence, i. e. sequencies always start at this date. (deprecated for tasks since v7.6.1, replaced by start_time and full_time)<br />
|-<br />
| 202 || end_date || Date or Time || Exclusive end of the event as Date for tasks and whole day appointments and as Time for normal appointments. (deprecated for tasks since v7.6.1, replaced by end_time and full_time)<br />
|-<br />
| 203 || note || String || Long description.<br />
|-<br />
| 204 || alarm || Number or Time || Specifies when to notify the participants as the number of minutes before the start of the appointment (-1 for "no alarm"). For tasks, the Time value specifies the absolute time when the user should be notified.<br />
|-<br />
| 209 || recurrence_type || Number || Specifies the type of the recurrence for a task sequence:<br />
{| cellspacing="0" border="1"<br />
| 0 || none (single event)<br />
|-<br />
| 1 || daily<br />
|-<br />
| 2 || weekly<br />
|-<br />
| 3 || monthly<br />
|-<br />
| 4 || yearly<br />
|}<br />
|-<br />
| 212 || days || Number || Specifies which days of the week are part of a sequence. The value is a bitfield with bit 0 indicating sunday, bit 1 indicating monday and so on. May be present if recurrence_type > 1. If allowed but not present, the value defaults to 127 (all 7 days).<br />
|-<br />
| 213 || day_in_month || Number || Specifies which day of a month is part of the sequence. Counting starts with 1. If the field "days" is also present, only days selected by that field are counted. If the number is bigger than the number of available days, the last available day is selected. Present if and only if recurrence_type > 2.<br />
|-<br />
| 214 || month || Number || Month of the year in yearly sequencies. 0 represents January, 1 represents February and so on. Present if and only if recurrence_type = 4.<br />
|-<br />
| 215 || interval || Number || Specifies an integer multiplier to the interval specified by recurrence_type. Present if and only if recurrence_type > 0. Must be 1 if recurrence_type = 4.<br />
|-<br />
| 216 || until || Date || Inclusive end date of a sequence. May be present only if recurrence_type > 0. The sequence has no end date if recurrence_type > 0 and this field is not present. Note: since this is a Date, the entire day after the midnight specified by the value is included.<br />
|-<br />
| 217 || notification || Boolean || If true, all participants are notified of any changes to this object. This flag is valid for the current change only, i. e. it is not stored in the database and is never sent by the server to the client.<br />
|-<br />
| 220 || participants || Array || Each element identifies a participant, user, group or booked resource as described in [[#Participant | participant table]].<br />
|-<br />
| 221 || users || Array || Each element represents a participant as described in [[#UserParticipantObject | User participant object]]. User groups are resolved and are represented by their members. Any user can occur only once.<br />
|-<br />
| 222 || occurrences || Number || Specifies how often a recurrence should appear. May be present only if recurrence_type > 0.<br />
|-<br />
| 223 || uid || String || Can only be written when the object is created. Internal and external globally unique identifier of the appointment or task. Is used to recognize appointments within iCal files. If this attribute is not written it contains an automatic generated UUID.<br />
|-<br />
| 224 || organizer || String || Contains the email address of the appointment organizer which is not necessarily an internal user. Not implemented for tasks.<br />
|-<br />
| 225 || sequence || Number || iCal sequence number. Not implemented for tasks. Must be incremented on update. Will be incremented by the server, if not set.<br />
|-<br />
| 226 || confirmations || Array || Each element represents a confirming participant as described in [[#ConfirmingParticipant | confirming participant]]. This can be internal and external user. Not implemented for tasks.<br />
|-<br />
| 227 || organizerId || Number || Contains the userIId of the appointment organizer if it is an internal user. Not implemented for tasks. (Introduced with 6.20.1)<br />
|-<br />
| 228 || principal || String || Contains the email address of the appointment principal which is not necessarily an internal user. Not implemented for tasks. (Introduced with 6.20.1)<br />
|-<br />
| 229 || principalId || Number || Contains the userIId of the appointment principal if it is an internal user. Not implemented for tasks. (Introduced with 6.20.1)<br />
|-<br />
| 401 || full_time || Boolean || True if the event is a whole day appointment or task, false otherwise.<br />
|}<br />
<br />
{| id="Participant" cellspacing="0" border="1"<br />
|+ align="bottom" | Participant identifier<br />
! Name !! Type !! Value<br />
|-<br />
| id || Number || User ID<br />
|-<br />
| type || Number || Type of participant:<br />
{|<br />
| 1 || user<br />
|-<br />
| 2 || user group<br />
|-<br />
| 3 || resource<br />
|-<br />
| 4 || resource group<br />
|-<br />
| 5 || external user<br />
|}<br />
|-<br />
| mail || String || mail address of an external participant<br />
|}<br />
<br />
{| id="UserParticipantObject" cellspacing="0" border="1"<br />
|+ align="bottom" | User participant object<br />
! Name !! Type !! Value<br />
|-<br />
| id || Number || User ID. Confirming for other users only works for appointments and not for tasks.<br />
|-<br />
| display_name || String || Displayable name of the participant.<br />
|-<br />
| confirmation || Number ||<br />
{| cellspacing="0" border="1"<br />
| 0 || none<br />
|-<br />
| 1 || accepted<br />
|-<br />
| 2 || declined<br />
|-<br />
| 3 || tentative<br />
|}<br />
|-<br />
| confirmmessage || String || Confirm Message of the participant<br />
|}<br />
<br />
{| id="ConfirmingParticipant" cellspacing="0" border="1"<br />
|+ align="bottom" | Confirming participant<br />
! Name !! Type !! Value<br />
|-<br />
| type || Number || Type of participant:<br />
{|<br />
| 1 || user<br />
|-<br />
| 5 || external user<br />
|}<br />
|-<br />
| mail || String || email address of external participant<br />
|-<br />
| display_name || String || display name of external participant<br />
|-<br />
| status || Number ||<br />
{|<br />
| 0 || none<br />
|-<br />
| 1 || accepted<br />
|-<br />
| 2 || declined<br />
|-<br />
| 3 || tentative<br />
|}<br />
|-<br />
| message || String || Confirm Message of the participant<br />
|}<br />
<br />
{| id="DetailedTaskData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed task data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 300 || status || Number || Status of the task:<br />
{| cellspacing="0" border="1"<br />
| 1 || not started<br />
|-<br />
| 2 || in progress<br />
|-<br />
| 3 || done<br />
|-<br />
| 4 || waiting<br />
|-<br />
| 5 || deferred<br />
|}<br />
|-<br />
| 301 || percent_completed || Number || How much of the task is completed. An integer number between 0 and 100.<br />
|-<br />
| 302 || actual_costs|| Number || A monetary attribute to store actual costs of a task. Allowed values must be in the range -9999999999.99 and 9999999999.99.<br />
|-<br />
| 303 || actual_duration<br />
|-<br />
| 304 || after_complete || Date || Deprecated. Only present in AJAX interface. Value will not be stored on OX server.<br />
|-<br />
| 305 || billing_information<br />
|-<br />
| 307 || target_costs|| Number || A monetary attribute to store target costs of a task. Allowed values must be in the range -9999999999.99 and 9999999999.99.<br />
|-<br />
| 308 || target_duration<br />
|-<br />
| 309 || priority || Number || 1 = LOW, 2 = MEDIUM, 3 = HIGH<br />
|-<br />
| 312 || currency<br />
|-<br />
| 313 || trip_meter<br />
|-<br />
| 314 || companies<br />
|-<br />
| 315 || date_completed<br />
|-<br />
| 201 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 202 || end_time || Date or Time || Exclusive end as Date for whole day tasks and as Time for normal tasks.<br />
|}<br />
<br />
=== Get a list of tasks ===<br />
<br />
PUT <code>/ajax/tasks?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for tasks are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]].<br />
<br />
Request body: An array of with object IDs of requested tasks.<br />
<br />
Response with timestamp: An array with task data. Each array element describes one task and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get updated tasks ===<br />
<br />
GET <code>/ajax/tasks?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for tasks are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>timestamp</code> – Timestamp of the last update of the requested tasks.<br />
* <code>ignore</code> – Which kinds of updates should be ignored. Omit this parameter or set it to "deleted" to not have deleted tasks identifier in the response. Set this parameter to "false" and the response contains deleted tasks identifier.<br />
<br />
Response with timestamp: An array with new, modified and deleted tasks. New and modified tasks are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted tasks would be identified by their object IDs as plain strings, without being part of a nested array.<br />
<br />
=== Get a task ===<br />
<br />
GET <code>/ajax/tasks?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested task.<br />
* <code>folder</code> – Object ID of the task's folder.<br />
<br />
Response with timestamp: An object containing all data of the requested task. The fields of the object are listed in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]]. The field id is not included.<br />
<br />
=== Update a task ===<br />
<br />
PUT <code>/ajax/tasks?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Folder Identifier through that the task is accessed. This is necessary for checking the permissions.<br />
* <code>id</code> – Object ID of the updated task.<br />
* <code>timestamp</code> – Timestamp of the updated task. If the task was modified after the specified timestamp, then the update must fail.<br />
<br />
Request body: Task object as described in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]]. Only modified fields are present.<br />
<br />
=== Create a task ===<br />
<br />
PUT <code>/ajax/tasks?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: Task object as described in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]]. The field id is not present.<br />
<br />
Response: A json objekt with attribute <code>id</code> of the newly created task.<br />
<br />
=== Delete task ===<br />
<br />
PUT <code>/ajax/tasks?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted tasks.<br />
<br />
Request body: An object in the field “id” and “folder”.<br />
<br />
Response: An array with object IDs of tasks which were modified after the specified timestamp and were therefore not deleted.<br />
<br />
=== Delete tasks (since v6.22) ===<br />
<br />
PUT <code>/ajax/tasks?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted tasks.<br />
<br />
Request body: An array of objects with the fields “id” and “folder”.<br />
<br />
Response: An array with object IDs of tasks which were modified after the specified timestamp and were therefore not deleted.<br />
<br />
=== Confirm task ===<br />
<br />
PUT <code>/ajax/tasks?action=confirm</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the to confirm task.<br />
* <code>folder</code> – ID of the folder through that the task is accessed.<br />
* <code>timestamp</code> – Timestamp of the last update of the to confirm task.<br />
<br />
Request body: An object with the fields "confirmation" and "confirmmessage" as described in [[#UserParticipantObject | User participant object]].<br />
<br />
Response: Nothing, except the standard response object with empty data, the timestamp of the confirmed and thereby updated task, and maybe errors.<br />
<br />
=== Search for tasks ===<br />
<br />
PUT <code>/ajax/tasks?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified , then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Request Body: A JSON object with attributes described in [[#SearchTasks | Search tasks]]<br />
<br />
{| id="SearchTasks" cellspacing="0" border="1"<br />
|+ align="bottom" | Search tasks<br />
! Name !! Type !! Value<br />
|-<br />
| pattern || String || Search pattern to find tasks. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.<br />
|-<br />
| folder || Number || (optional) Defines the folder to search for tasks in. If this is omitted in all task folders will be searched.<br />
|-<br />
| start || Date or Time || (optional) Inclusive start date for a time range the tasks should end in. If start is omitted end is ignored.<br />
|-<br />
| end || Date or Time || (optional) Exclusive end date for a time range the tasks should end in. If this parameter is omitted the time range has an open end.<br />
|}<br />
<br />
Response with timestamp: An array with matching tasks. Tasks are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
== Module "contacts" ==<br />
<br />
The contacts module is used to access contact information.<br />
<br />
=== Get all contacts ===<br />
<br />
GET <code>/ajax/contacts?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried (optional from 6.22.2 on: If not set, the contents of all visible folders are used instead).<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>collation</code> (preliminary, since 6.20) – allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.<br />
<br />
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
{| id="DetailedContactData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed contact data<br />
! ID !! Displayed name !! Name !! Type !! Value<br />
|-<br />
| 223 || || uid || String || Can only be written when the object is created. Internal and external globally unique identifier of the contact. Is used to recognize contacts within vCard files. If this attribute is not written it contains an automatic generated UUID.<br />
|-<br />
| 500 || Display name || display_name || String<br />
|-<br />
| 501 || Given name || first_name || String || First name.<br />
|-<br />
| 502 || Sur name || last_name || String || Last name.<br />
|-<br />
| 503 || Middle name || second_name || String<br />
|-<br />
| 504 || Suffix || suffix || String<br />
|-<br />
| 505 || Title || title || String<br />
|-<br />
| 506 || Street home || street_home || String<br />
|-<br />
| 507 || Postal code home || postal_code_home || String<br />
|-<br />
| 508 || City home || city_home || String<br />
|-<br />
| 509 || State home || state_home || String<br />
|-<br />
| 510 || Country home || country_home || String<br />
|-<br />
| 511 || Birthday || birthday || Date<br />
|-<br />
| 512 || Martial status || marital_status || String<br />
|-<br />
| 513 || Number of children || number_of_children || String<br />
|-<br />
| 514 || Profession || profession || String<br />
|-<br />
| 515 || Nickname || nickname || String<br />
|-<br />
| 516 || Spouse name || spouse_name || String<br />
|-<br />
| 517 || Anniversay || anniversary || Date<br />
|-<br />
| 518 || Note || note || String<br />
|-<br />
| 519 || Department || department || String<br />
|-<br />
| 520 || Position || position || String<br />
|-<br />
| 521 || Employee type || employee_type || String<br />
|-<br />
| 522 || Room number || room_number || String<br />
|-<br />
| 523 || Street business || street_business || String<br />
|-<br />
| 524 || || internal_userid || Number<br />
|-<br />
| 525 || Postal code business || postal_code_business || String<br />
|-<br />
| 526 || City business || city_business || String<br />
|-<br />
| 527 || State business || state_business || String<br />
|-<br />
| 528 || Country business || country_business || String<br />
|-<br />
| 529 || Number of employee || number_of_employees || String<br />
|-<br />
| 530 || Sales volume || sales_volume || String<br />
|-<br />
| 531 || Tax id || tax_id || String<br />
|-<br />
| 532 || Commercial register || commercial_register || String<br />
|-<br />
| 533 || Branches || branches || String<br />
|-<br />
| 534 || Business category || business_category || String<br />
|-<br />
| 535 || Info || info || String<br />
|-<br />
| 536 || Manager's name || manager_name || String<br />
|-<br />
| 537 || Assistant's name || assistant_name || String<br />
|-<br />
| 538 || Street other || street_other || String<br />
|-<br />
| 539 || City other || city_other || String<br />
|-<br />
| 540 || Postal code other || postal_code_other || String<br />
|-<br />
| 541 || Country other || country_other || String<br />
|-<br />
| 542 || Telephone business 1 || telephone_business1 || String<br />
|-<br />
| 543 || Telephone business 2 || telephone_business2 || String<br />
|-<br />
| 544 || FAX business || fax_business || String<br />
|-<br />
| 545 || Telephone callback || telephone_callback || String<br />
|-<br />
| 546 || Telephone car || telephone_car || String<br />
|-<br />
| 547 || Telephone company || telephone_company || String<br />
|-<br />
| 548 || Telephone home 1 || telephone_home1 || String<br />
|-<br />
| 549 || Telephone home 2 || telephone_home2 || String<br />
|-<br />
| 550 || FAX home || fax_home || String<br />
|-<br />
| 551 || Cellular telephone 1 || cellular_telephone1 || String<br />
|-<br />
| 552 || Cellular telephone 2 || cellular_telephone2 || String<br />
|-<br />
| 553 || Telephone other || telephone_other || String<br />
|-<br />
| 554 || FAX other || fax_other || String<br />
|-<br />
| 555 || Email 1 || email1 || String<br />
|-<br />
| 556 || Email 2 || email2 || String<br />
|-<br />
| 557 || Email 3 || email3 || String<br />
|-<br />
| 558 || URL || url || String<br />
|-<br />
| 559 || Telephone ISDN || telephone_isdn || String<br />
|-<br />
| 560 || Telephone pager || telephone_pager || String<br />
|-<br />
| 561 || Telephone primary || telephone_primary || String<br />
|-<br />
| 562 || Telephone radio || telephone_radio || String<br />
|-<br />
| 563 || Telephone telex || telephone_telex || String<br />
|-<br />
| 564 || Telephone TTY/TDD || telephone_ttytdd || String<br />
|-<br />
| 565 || Instantmessenger 1 || instant_messenger1 || String<br />
|-<br />
| 566 || Instantmessenger 2 || instant_messenger2 || String<br />
|-<br />
| 567 || Telephone IP || telephone_ip || String<br />
|-<br />
| 568 || Telephone assostant || telephone_assistant || String<br />
|-<br />
| 569 || Company || company || String<br />
|-<br />
| 570 || || image1 || String<br />
|-<br />
| 571 || Dynamic Field 1 || userfield01 || String<br />
|-<br />
| 572 || Dynamic Field 2 || userfield02 || String<br />
|-<br />
| 573 || Dynamic Field 3 || userfield03 || String<br />
|-<br />
| 574 || Dynamic Field 4 || userfield04 || String<br />
|-<br />
| 575 || Dynamic Field 5 || userfield05 || String<br />
|-<br />
| 576 || Dynamic Field 6 || userfield06 || String<br />
|-<br />
| 577 || Dynamic Field 7 || userfield07 || String<br />
|-<br />
| 578 || Dynamic Field 8 || userfield08 || String<br />
|-<br />
| 579 || Dynamic Field 9 || userfield09 || String<br />
|-<br />
| 580 || Dynamic Field 10 || userfield10 || String<br />
|-<br />
| 581 || Dynamic Field 11 || userfield11 || String<br />
|-<br />
| 582 || Dynamic Field 12 || userfield12 || String<br />
|-<br />
| 583 || Dynamic Field 13 || userfield13 || String<br />
|-<br />
| 584 || Dynamic Field 14 || userfield14 || String<br />
|-<br />
| 585 || Dynamic Field 15 || userfield15 || String<br />
|-<br />
| 586 || Dynamic Field 16 || userfield16 || String<br />
|-<br />
| 587 || Dynamic Field 17 || userfield17 || String<br />
|-<br />
| 588 || Dynamic Field 18 || userfield18 || String<br />
|-<br />
| 589 || Dynamic Field 19 || userfield19 || String<br />
|-<br />
| 590 || Dynamic Field 20 || userfield20 || String || Contains a UUID if one was assigned (after 6.18.2)<br />
|-<br />
| 592 || || distribution_list || Array || If this contact is a distribution list, then this field is an array of objects. Each object describes a member of the list as defined in [[#DistributionListMember | Distribution list member]].<br />
|-<br />
| 594 || Number of distributionlists || number_of_distribution_list || Number<br />
|-<br />
| 596 || || number_of_images || Number<br />
|-<br />
| 597 || || image_last_modified || Timestamp<br />
|-<br />
| 598 || State other || state_other || String<br />
|-<br />
| 599 || || file_as || String<br />
|-<br />
| 601 || || image1_content_type || String<br />
|-<br />
| 602 || || mark_as_distributionlist || Boolean<br />
|-<br />
| 605 || Default address || default_address || Number<br />
|-<br />
| 606 || || image1_url || String<br />
|-<br />
| 608 || || useCount || Number || In case of sorting purposes the column 609 is also available, which places global address book contacts at the beginning of the result. If 609 is used, the order direction (ASC, DESC) is ignored.<br />
|-<br />
| 610 || || yomiFirstName || String || Kana based representation for the First Name. Commonly used in japanese environments for searchin/sorting issues. (since 6.20)<br />
|-<br />
| 611 || || yomiLastName || String || Kana based representation for the Last Name. Commonly used in japanese environments for searchin/sorting issues. (since 6.20)<br />
|-<br />
| 612 || || yomiCompany || String || Kana based representation for the Company. Commonly used in japanese environments for searchin/sorting issues. (since 6.20)<br />
|-<br />
| 613 || || addressHome || String || Support for Outlook 'home' address field. (since 6.20.1)<br />
|-<br />
| 614 || || addressBusiness || String || Support for Outlook 'business' address field. (since 6.20.1)<br />
|-<br />
| 615 || || addressOther || String || Support for Outlook 'other' address field. (since 6.20.1)<br />
|}<br />
<br />
<br />
{| id="DistributionListMember" cellspacing="0" border="1"<br />
|+ align="bottom" | Distribution list member<br />
! Name !! Type !! Value<br />
|-<br />
| id || String || Object ID of the member's contact if the member is an existing contact.<br />
|-<br />
| folder_id || String || Parent folder ID of the member's contact if the member is an existing contact (preliminary, from 6.22 on).<br />
|-<br />
| display_name || String || Display name<br />
|-<br />
| mail || String || Email address (mandatory before 6.22, afterwards optional if you are referring to an internal contact)<br />
|-<br />
| mail_field || Number || Which email field of an existing contact (if any) is used for the mail field.<br />
{| cellspacing="0" border="1"<br />
| 0 || independent contact<br />
|-<br />
| 1 || default email field (email1)<br />
|-<br />
| 2 || second email field (email2)<br />
|-<br />
| 3 || third email field (email3)<br />
|}<br />
|}<br />
<br />
=== Get a list of contacts ===<br />
<br />
PUT <code>/ajax/contacts?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]].<br />
<br />
Request body: An array with objects. Each object contains fields “id” and “folder” of requested contacts.<br />
<br />
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get a list of users ===<br />
<br />
PUT <code>/ajax/contacts?action=listuser</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]].<br />
<br />
Request body: An array with id<br />
<br />
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
Available with SP4<br />
<br />
=== Get updated contacts ===<br />
<br />
GET <code>/ajax/contacts?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for contacts are defined in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>timestamp</code> – Timestamp of the last update of the requested contacts.<br />
* <code>ignore</code> (mandatory - should be set to "deleted") (deprecated) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.<br />
<br />
Response with timestamp: An array with new, modified and deleted contacts. New and modified contacts are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted contacts (should the <code>ignore</code> parameter be ever implemented) would be identified by their object IDs as plain strings, without being part of a nested array.<br />
<br />
=== Get a contact ===<br />
<br />
GET <code>/ajax/contacts?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested contact.<br />
* <code>folder</code> – Object ID of the contact's folder.<br />
<br />
Response with timestamp: An object containing all data of the requested contact. The fields of the object are listed in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]]. The field id is not included.<br />
<br />
=== Get contact by user ID ===<br />
<br />
GET <code>/ajax/contacts?action=getuser</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – User ID (not Object ID) of the requested user.<br />
<br />
Response with timestamp: An object containing all data of the requested contact. The fields of the object are listed in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]]. <br />
<br />
Available with SP4 package.<br />
<br />
=== Update a contact ===<br />
<br />
PUT <code>/ajax/contacts?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Folder identifier through that the contact is accessed. This is necessary for checking the permissions.<br />
* <code>id</code> – Object ID of the updated contact.<br />
* <code>timestamp</code> – Timestamp of the updated contact. If the contact was modified after the specified timestamp, then the update must fail.<br />
<br />
Request body: Contact object as described in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]]. Only modified fields are present.<br />
<br />
To remove some contact image send the image attribute set to <code>null</code>.<br />
<br />
To change or add some contact image the PUT command must be replaced with a POST command and all data must be provided within a <code>multipart/form-data</code> body. The normal request body must be placed into a form field named <code>json</code> while the image file must be placed in a file field named <code>file</code>. The response is then an HTML page as described in section [[#File_uploads | File uploads]].<br />
<br />
=== Create a contact ===<br />
<br />
PUT <code>/ajax/contacts?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: Contact object as described in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]]. The field id is not included.<br />
<br />
Response: A json objekt with attribute <code>id</code> of the newly created contact.<br />
<br />
To add some contact image the PUT command must be replaced with a POST command and all data must be provided within a <code>multipart/form-data</code> body. The normal request body must be placed into a form field named <code>json</code> while the image file must be placed in a file field named <code>file</code>. The response is then an HTML page as described in section [[#File uploads | File uploads]].<br />
<br />
=== Delete a contact ===<br />
<br />
PUT <code>/ajax/contacts?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted contacts.<br />
<br />
Request body: An object with the fields “id” and “folder”.<br />
<br />
=== Delete contacts (since v6.22)===<br />
<br />
PUT <code>/ajax/contacts?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted contacts.<br />
<br />
Request body: An array of objects with the fields “id” and “folder”.<br />
<br />
=== Search contacts ===<br />
<br />
PUT <code>/ajax/contacts?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – The requested fields<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified. In case of use of column 609 (use count depending order for collected contacts with global address book) the parameter "order" ist NOT necessary and will be ignored.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>collation</code> (preliminary, since 6.20) – allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.<br />
<br />
Request body: An Object as described in [[#SearchContacts | Search contacts]].<br />
<br />
{| id="SearchContacts" cellspacing="0" border="1"<br />
|+ align="bottom" | Search contacts<br />
! Name !! Type !! Value<br />
|-<br />
| pattern || String || Search pattern to find contacts. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves. Matching is performed against any substring of the field <code>display_name</code>.<br />
|-<br />
| startletter || String || Search contacts with the given startletter. If this field is present, the pattern is matched against the contact field which is specified by the property contact_first_letter_field on the server (default: last name). Otherwise, the pattern is matched against the display name.<br />
|-<br />
| folder || Array of Number || If a list of folder identifiers or at least a single folder identifier is given, only in that folders will be searched for contacts. This paramenter is optional but searching in all contact folders that are viewable and where objects can be read in is more expensive on that database than searching in a dedicated number of them. The possibility to provide here an array of folder identifier has been added with 6.10.<br />
|}<br />
<br />
Alternative request body: An Object as described in [[#SearchContactsAlternative | Search contacts alternative]].<br />
<br />
{| id="SearchContactsAlternative" cellspacing="0" border="1"<br />
|+ align="bottom" | Search contacts alternative<br />
! Name !! Type !! Value<br />
|-<br />
| last_name || String || Searches contacts where the last name match with the given last name.<br />
|-<br />
| first_name || String || Searches contacts where the first name match with the given first name.<br />
|-<br />
| display_name || String || Searches contacts where the display name match with the given display name.<br />
|-<br />
| email1 || String || Searches contacts where the email1 address match with the given search pattern. (requires version >= 6.12)<br />
|-<br />
| email2 || String || Searches contacts where the email2 address match with the given search pattern. (requires version >= 6.12)<br />
|-<br />
| email3 || String || Searches contacts where the email3 address match with the given search pattern. (requires version >= 6.12)<br />
|-<br />
| company || String || Searches contacts where the company match with the given search pattern. (requires version >= 6.12)<br />
|-<br />
| categories || String || Searches contacts where the categories match with the given search pattern. <br />
|-<br />
| orSearch || Boolean || If set to true, a contact is returned if any specified pattern matches at the start of the corresponding field. Otherwise, a contact is returned if all specified patterns match any substring of the corresponding field.<br />
|-<br />
| emailAutoComplete || Boolean || If set to true, results are guaranteed to contain at least one email adress and the search is performed as if orSearch were set to true. The actual value of orSearch is ignored.<br />
|-<br />
| exactMatch || Boolean || If set to true, contacts are returned where the specified patterns match the corresponding fields exactly. Otherwise, a 'startsWith' or 'substring' comparison is used based on the 'orSearch' parameter. (requires version > 6.22.1)<br />
|}<br />
<br />
Response: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Search contacts by filter (since 6.20) ===<br />
<br />
PUT <code>/ajax/contacts?action=advancedSearch</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – The requested fields<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified. <br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>collation</code> (preliminary, since 6.20) – allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.<br />
<br />
Request body: An Object as described in [[#Module_.22search.22_.28alternative_suggestion.2C_still_preliminary.29 | Search Filter]]<br />
<br />
Response: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Search contacts by anniversary (Since 6.22.1, Preliminary) ===<br />
<br />
Find contacts whose anniversary falls into a timerange.<br />
<br />
GET <code>/ajax/contacts?action=anniversaries</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>start</code> – The lower (inclusive) limit of the requested time-range.<br />
* <code>end</code> – The upper (exclusive) limit of the requested time-range.<br />
* <code>columns</code> – The requested fields.<br />
* <code>folder</code> (optional) – Object ID of the parent folder that is searched. If not set, all visible folders are used.<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If not specified, the results are sorted ascending by their anniversary in the supplied timerange. If this parameter is specified, then the parameter order must be also specified. <br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>collation</code> (optional) – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.<br />
<br />
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Search contacts by birthday (Since 6.22.1, Preliminary) ===<br />
<br />
Find contacts whose birthday falls into a timerange.<br />
<br />
GET <code>/ajax/contacts?action=birthdays</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>start</code> – The lower (inclusive) limit of the requested time-range.<br />
* <code>end</code> – The upper (exclusive) limit of the requested time-range.<br />
* <code>columns</code> – The requested fields.<br />
* <code>folder</code> (optional) – Object ID of the parent folder that is searched. If not set, all visible folders are used.<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If not specified, the results are sorted ascending by their birthday in the supplied timerange. If this parameter is specified, then the parameter order must be also specified. <br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>collation</code> (optional) – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.<br />
<br />
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Auto-complete contacts (Since 7.6.1, Preliminary) ===<br />
<br />
Find contacts based on a prefix, usually used to auto-complete e-mail recipients while the user is typing.<br />
<br />
GET <code>/ajax/contacts?action=autocomplete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>query</code> – The query to search for.<br />
* <code>folder</code> (optional) – Object ID of the parent folder that is searched. If not set, all visible folders are used.<br />
* <code>email</code> (optional) – Whether to only include contacts with at least one e-mail address. Defaults to "true".<br />
* <code>columns</code> – The requested fields.<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If not specified, the results are sorted ascending by their birthday in the supplied timerange. If this parameter is specified, then the parameter order must be also specified. <br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>collation</code> (optional) – Allows you to specify a collation to sort the contacts by. As of 6.20, only supports "gbk" and "gb2312", not needed for other languages. Parameter <code>sort</code> should be set for this to work.<br />
<br />
Response with timestamp: An array with contact data. Each array element describes one contact and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
== Module "calendar" ==<br />
<br />
The calendar module is used to access calendar data.<br />
<br />
=== Get all appointments ===<br />
<br />
GET <code>/ajax/calendar?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> (optional) – Object ID of the folder, whose contents are queried. If not specified, defaults to all calendar folders.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]].<br />
* <code>start</code> – Lower inclusive limit of the queried range as a Date. Only appointments which start on or after this date are returned.<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which end before this date are returned.<br />
* <code>recurrence_master</code> – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.<br />
* <code>showPrivate</code> (optional) – only works in shared folders: When enabled, shows private appointments of the folder owner. Such appointments are anonymized by stripping away all information except start date, end date and recurrence information (since 6.18)<br />
<br />
Response with timestamp: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Appointment sequencies are broken up into individual appointments and each occurrence of a sequence in the requested range is returned separately. The appointments are sorted in ascending order by the field start_date.<br />
<br />
{| id="DetailedAppointmentData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed appointment data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 206 || recurrence_id || Number || Object ID of the entire appointment sequence. Present on series and change exception appointments. Equals to object identifier on series appointment and is different to object identifier on change exceptions.<br />
|-<br />
| 207 || recurrence_position || Number || 1-based position of an individual appointment in a sequence. Present if and only if recurrence_type > 0.<br />
|-<br />
| 208 || recurrence_date_position || Date || Date of an individual appointment in a sequence. Present if and only if recurrence_type > 0.<br />
|-<br />
| 210 || change_exceptions || Array || An array of Dates, representing all change exceptions of a sequence.<br />
|-<br />
| 211 || delete_exceptions || Array || An array of Dates, representing all delete exceptions of a sequence.<br />
|-<br />
| 400 || location || String || Location<br />
|-<br />
| 402 || shown_as || Number || Describes, how this appointment appears in availability queries:<br />
{| cellspacing="0" border="1"<br />
| 1 || reserved<br />
|-<br />
| 2 || temporary<br />
|-<br />
| 3 || absent<br />
|-<br />
| 4 || free<br />
|}<br />
|-<br />
| 408 || timezone || String || Timezone<br />
|-<br />
| 410 || recurrence_start || Date || Start of a sequence without time<br />
|-<br />
| || ignore_conflicts || Boolean || Ignore soft conflicts for the new or modified appointment. This flag is valid for the current change only, i. e. it is not stored in the database and is never sent by the server to the client. <br />
|}<br />
<br />
=== Get appointment information ===<br />
<br />
GET <code>/ajax/calendar?action=has</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>start</code> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br />
<br />
Response is an array of booleans. Array length is the number of days. Each entry in the array corresponds with one day in the range that was queried, explaining whether there is an appointment on this day or not.<br />
<br />
=== Get a list of appointments ===<br />
<br />
PUT <code>/ajax/calendar?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]].<br />
* <code>recurrence_master</code> – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.<br />
<br />
Request body: An array with full object IDs (folder, id and optionally either recurrence_position or recurrence_date_position) of requested appointments.<br />
<br />
Response with timestamp: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
{| id="FullIdentifierForAnAppointment" cellspacing="0" border="1"<br />
|+ align="bottom" | Full identifier for an appointment<br />
! Name !! Type !! Value<br />
|-<br />
| id || String || Object ID<br />
|-<br />
| pos || Number || Value of the field recurrence_position, if present in the appointment.<br />
|}<br />
<br />
=== Get updated appointments ===<br />
<br />
GET <code>/ajax/calendar?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]].<br />
* <code>timestamp</code> – Timestamp of the last update of the requested appointments.<br />
* <code>start</code> (optional) – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br />
* <code>end</code> (optional) – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br />
* <code>ignore</code> (mandatory - should be set to "deleted") (deprecated) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.<br />
* <code>recurrence_master</code> – Extract the recurrence to several appointments. The default value is false so every appointment of the recurrence will be calculated.<br />
* <code>showPrivate</code> (optional) – only works in shared folders: When enabled, shows private appointments of the folder owner. Such appointments are anonymized by stripping away all information except start date, end date and recurrence information (since 6.18)<br />
<br />
Response with timestamp: An array with new, modified and deleted appointments. New and modified appointments are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted appointments (should the <code>ignore</code> parameter be ever implemented) would be identified by objects described in [[#FullIdentifierForAnAppointment | Full identifier for an appointment]] instead of arrays. Appointment sequencies are broken up into individual appointments and each modified occurrence of a sequence in the requested range is returned separately. The appointments are sorted in ascending order by the field start_date.<br />
<br />
=== Get an appointment ===<br />
<br />
GET <code>/ajax/calendar?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested appointment.<br />
* <code>folder</code> – Folder ID of the requested appointment.<br />
* <code>recurrence_position</code> (optional) – Recurrence Position requested appointment.<br />
<br />
Response with timestamp: An object containing all data of the requested appointment. The fields of the object are listed in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]]. The field id is not included.<br />
<br />
=== Update an appointment ===<br />
<br />
PUT <code>/ajax/calendar?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the updated appointment.<br />
* <code>folder</code> - Object ID of the appointment's folder.<br />
* <code>timestamp</code> – Timestamp of the updated appointment. If the appointment was modified after the specified timestamp, then the update must fail.<br />
<br />
Request body: Appointment object as described in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]]. The field recurrence_id is always present if it is present in the original appointment. The field recurrence_position is present if it is present in the original appointment and only this single appointment should be modified. The field id is not present because it is already included as a parameter. Other fields are present only if modified.<br />
<br />
=== Create an appointment ===<br />
PUT <code>/ajax/calendar?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: Appointment object as described in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[#DetailedAppointmentData | Detailed appointment data]]. The field id is not present.<br />
<br />
Response: If the appointment was created successfully, an object with the attribute <code>id</code> of the newly created appointment. If the appointment could not be created due to conflicts, the response body is an object with the field <code>conflicts</code>, which is an array of appointment objects which caused the conflict. Each appointment object which represents a resource conflict contains an additional field <code>hard_conflict</code> with the Boolean value true. If the user does not have read access to a conflicting appointment, only the fields <code>id</code>, <code>start_date</code>, <code>end_date</code>, <code>shown_as</code> and <code>participants</code> are present and the field <code>participants</code> contains only the participants which caused the conflict.<br />
<br />
=== Delete an appointment ===<br />
<br />
PUT <code>/ajax/calendar?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted appointments.<br />
<br />
Request body: The appointment object to delete. The fields for the object are described in [[#FullIdentifierForAnAppointment | Full identifier for an appointment]]. <br />
<br />
Response: An array of objects identifying the appointments which were modified after the specified timestamp and were therefore not deleted. The fields of each object are described in [[#FullIdentifierForAnAppointment | Full identifier for an appointment]].<br />
<br />
=== Delete appointments (since v6.22) ===<br />
<br />
PUT <code>/ajax/calendar?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted appointments.<br />
<br />
Request body: An array of appointment objects to delete. The fields for the object are described in [[#FullIdentifierForAnAppointment | Full identifier for an appointment]]. <br />
<br />
Response: An array of objects identifying the appointments which were modified after the specified timestamp and were therefore not deleted. The fields of each object are described in [[#FullIdentifierForAnAppointment | Full identifier for an appointment]].<br />
<br />
=== Confirm appointment ===<br />
<br />
PUT <code>/ajax/calendar?action=confirm</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the appointment to confirm.<br />
* <code>occurrence</code> – The numeric identifier of the occurrence to which the confirmation applies (in case "id" denotes a series appointment). Available with v7.6.0<br />
* <code>folder</code> – ID of the folder through which the appointment is accessed.<br />
* <code>timestamp</code> – Timestamp of the last update of the to confirmed appointment.<br />
<br />
Request body: An object with the fields "confirmation", "confirmmessage" and "id" (optional) as described in [[#UserParticipantObject | User participant object]].<br />
<br />
Response: Nothing, except the standard response object with empty data, the timestamp of the confirmed and thereby updated task, and maybe errors.<br />
<br />
=== Free & Busy ===<br />
<br />
GET <code>/ajax/calendar?action=freebusy</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> - Internal user id. Must be obtained from the contact module.<br />
* <code>type</code> - Constant for user or resource (1 for users, 3 for resources)<br />
* <code>start</code> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br />
<br />
Response: An array of objects identifying the appointments which lie between start and end as described.<br><br />
This objects consist of:<br />
{| id="FreeAndBusyAppointment" cellspacing="0" border="1"<br />
! Name !! Type !! Value<br />
|-<br />
| shown_as || Number || Describes, how this appointment appears in availability queries:<br />
{| cellspacing="0" border="1"<br />
| 1 || reserved<br />
|-<br />
| 2 || temporary<br />
|-<br />
| 3 || absent<br />
|-<br />
| 4 || free<br />
|}<br />
|-<br />
| start_date || Date or Time || see [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]]<br />
|- <br />
| end_date || Date or Time || see [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]]<br />
|-<br />
| id || String || Object ID<br />
|-<br />
| folder_id || String || Folder ID. Only set, if the user has the right to see the object. (added 2009-08-18/6.12) <br />
|-<br />
| full_time || Boolean || True if the appointment is a whole day appointment, not present otherwise.<br />
|}<br />
<br />
=== Search appointments ===<br />
<br />
PUT <code>/ajax/calendar?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – The requested fields<br />
<br />
Request body: An Object as described in [[#SearchAppointments | Search appointments]].<br />
<br />
{| id="SearchAppointments" cellspacing="0" border="1"<br />
|+ align="bottom" | Search appointments<br />
! Name !! Type !! Value<br />
|-<br />
| pattern || String || Search pattern to find appointments. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.<br />
|-<br />
| startletter || String || Search appointments with the given starting letter.<br />
|}<br />
<br />
Request body: An Object as described in [[#SearchAppointments | Search appointments]].<br />
<br />
Response: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get new appointments ===<br />
<br />
GET <code>/ajax/calendar?action=newappointments</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – The requested fields<br />
* <code>start</code> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified and holds a column number, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>limit</code> – limits the number of returned object to the given value.<br />
<br />
Response: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Resolve UID ===<br />
<br />
GET <code>/ajax/calendar?action=resolveuid</code><br />
<br />
Parameters<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>uid</code> – The UID to be resolved.<br />
<br />
Response: An object object with the field "id" containing the ox-object id, if existing, an error message otherwise.<br />
<br />
=== Get all Change Exceptions (Since v7.2.0) ===<br />
<br />
GET <code>/ajax/calendar?action=getChangeExceptions</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object id of the appointment series.<br />
* <code>folder</code> – Folder ID of the requested appointments. <br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier.<br />
<br />
Response with timestamp: An array with appointment data. Each array element describes one appointment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
== Module "mail" ==<br />
<br />
The mail module is used to access mail data.<br />
<br />
When mails are stored on an IMAP server, some functionality is not available due to restrictions of the IMAP protocol. Such functionality is marked with "not IMAP".<br />
<br />
=== Get mail count ===<br />
<br />
GET <code>/ajax/mail?action=count</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder whose mail count is queried<br />
<br />
Response (not IMAP: with timestamp): An integer value representing folder's mail count<br />
<br />
=== Get all mails ===<br />
<br />
GET <code>/ajax/mail?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#DetailedMailData | Detailed mail data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>left_hand_limit</code> - A positive integer number to specify the "right-hand" limit of the range to return<br />
* <code>right_hand_limit</code> - A positive integer number to specify the "left-hand" limit of the range to return<br />
* <code>limit</code> - A positive integer number to specify how many items shall be returned according to given sorting; overrides <code>left_hand_limit</code>/<code>right_hand_limit</code> parameters and is equal to <code>left_hand_limit=0</code> and <code>right_hand_limit=&lt;limit&gt;</code><br />
<br />
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
{| id="DetailedMailData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed mail data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 102 || color_label || Number || Color number used by Outlook to label the object. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers between 0 and 10 (inclusive).<br />
|-<br />
| 600 || id || String || Object ID<br />
|-<br />
| 601 || folder_id || String || Object ID of the parent folder<br />
|-<br />
| 602 || attachment || Boolean || Specifies whether this mail has attachments.<br />
|-<br />
| 603 || from || Array || Each element is a two-element array specifying one sender. The first element of each address is the personal name, the second element is the email address. Missing address parts are represented by <code>null</code> values.<br />
|-<br />
| 604 || to || Array || Each element is a two-element array (see the from field) specifying one receiver.<br />
|-<br />
| 605 || cc || Array || Each element is a two-element array (see the from field) specifying one carbon-copy receiver.<br />
|-<br />
| 606 || bcc || Array || Each element is a two-element array (see the from field) specifying one blind carbon-copy receiver.<br />
|-<br />
| 607 || subject || String || Subject line.<br />
|-<br />
| 608 || size || Number || Size of the mail in bytes.<br />
|-<br />
| 609 || sent_date || Time || Date and time as specified in the mail by the sending client.<br />
|-<br />
| 610 || received_date || Time || Date and time as measured by the receiving server.<br />
|-<br />
| 611 || flags || Number || Various system flags. A sum of zero or more of following values:<br />
{| cellspacing="0" border="1"<br />
| 1 || answered<br />
|-<br />
| 2 || deleted<br />
|-<br />
| 4 || draft<br />
|-<br />
| 8 || flagged<br />
|-<br />
| 16 || recent<br />
|-<br />
| 32 || seen<br />
|-<br />
| 64 || user<br />
|-<br />
| 256 || forwarded<br />
|}<br />
See javax.mail.Flags.Flag for details.<br />
|-<br />
| 612 || level || Number || Zero-based nesting level in a thread.<br />
|-<br />
| 613 || disp_notification_to || String || Content of message's header “Disposition-Notification-To”<br />
|-<br />
| 614 || priority || Number || Value of message's “X-Priority” header:<br />
{| cellspacing="0" border="1"<br />
| 0 || No priority<br />
|-<br />
| 5 || Very Low<br />
|-<br />
| 4 || Low<br />
|-<br />
| 3 || Normal<br />
|-<br />
| 2 || High<br />
|-<br />
| 1 || Very High<br />
|}<br />
|-<br />
| 615 || msg_ref || String || Message reference on reply/forward.<br />
|-<br />
| 651 || flag_seen || String || Special field to sort mails by seen status<br />
|-<br />
| 652 || account_name || String || Message's account name.<br />
|-<br />
| 653 || account_id || int || Message's account identifier. Since v6.20.2<br />
|-<br />
| || user || Array || An array with user-defined flags as strings.<br />
|-<br />
| || headers || Object || An object with a field for every non-standard header. The header name is the field name. The header value is the value of the field as string.<br />
|-<br />
| || attachments || Array || Each element is an attachment as described in [[#Attachment | Attachment]]. The first element is the mail text. If the mail has multiple representations (multipart-alternative), then the alternatives are placed after the mail text and have the field disp set to alternative.<br />
|-<br />
| || nested_msgs || Array || Each element is a mail object as described in this table, except for fields id, folder_id and attachment.<br />
|-<br />
| || truncated || boolean || true/false if the mail content was trimmed. Since v7.6.1<br />
|-<br />
| || source || String || RFC822 source of the mail. Only present for <tt>action=get&attach_src=true</tt><br />
|}<br />
<br />
{| id="Attachment" cellspacing="0" border="1"<br />
|+ align="bottom" | Attachment<br />
! Name !! Type !! Value<br />
|-<br />
| id || String || Object ID (unique only inside the same message)<br />
|-<br />
| content_type || String || MIME type<br />
|-<br />
| content || String || Content as text. Present only if easily convertible to text.<br />
|-<br />
| filename || String || Displayed filename (mutually exclusive with content).<br />
|-<br />
| size || Number || Size of the attachment in bytes.<br />
|-<br />
| disp || String || Attachment's disposition: null, inline, attachment or alternative.<br />
|}<br />
<br />
=== Get all mail conversations (since v7.x) ===<br />
<br />
GET <code>/ajax/mail?action=threadedAll</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#DetailedMailData | Detailed mail data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified. <b>Note</b>: Applies only to root-level messages.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified. <b>Note</b>: Applies only to root-level messages.<br />
* <code>includeSent</code> - A boolean value to signal that conversations also include messages taken from special "sent" aka "sent items" folder<br />
* <code>left_hand_limit</code> - A positive integer number to specify the "right-hand" limit of the range to return. <b>Note</b>: Applies only to root-level messages.<br />
* <code>right_hand_limit</code> - A positive integer number to specify the "left-hand" limit of the range to return. <b>Note</b>: Applies only to root-level messages.<br />
* <code>limit</code> - A positive integer number to specify how many items shall be returned according to given sorting; overrides <code>left_hand_limit</code>/<code>right_hand_limit</code> parameters and is equal to <code>left_hand_limit=0</code> and <code>right_hand_limit=&lt;limit&gt;</code>. <b>Note</b>: Applies only to root-level messages.<br />
<br />
Response (not IMAP: with timestamp): An JSON array consisting of JSON objects, each representing a conversation's root message along with its message thread. The root message's JSON object is filled according to specified columns and is enhanced by special <code>"thread"</code> JSON field representing the full message thread (including the root message itself). The <code>"thread"</code> JSON field is a JSON array of JSON objects; each representing a message in the conversation sorted by time-line, also filled with specified columns. E.g.<br />
<br />
<pre><br />
{<br />
"flags":32,<br />
"color_label":0,<br />
"unreadCount":0,<br />
"id":"263852",<br />
"folder_id":"default0/INBOX",<br />
"thread":[<br />
{<br />
"id":"263852",<br />
"folder_id":"default0/INBOX",<br />
"flags":32,<br />
"color_label":0<br />
},<br />
{<br />
"id":"263853",<br />
"folder_id":"default0/INBOX",<br />
"flags":32,<br />
"color_label":0<br />
},<br />
{<br />
"id":"26323",<br />
"folder_id":"default0/Sent",<br />
"flags":32,<br />
"color_label":0<br />
},<br />
{<br />
"id":"263854",<br />
"folder_id":"default0/INBOX",<br />
"flags":32,<br />
"color_label":0<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
=== Search mails ===<br />
<br />
PUT <code>/ajax/mail?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for appointments are defined in [[#DetailedMailData | Detailed mail data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response or the string “thread” to return thread-sorted messages. If this parameter is specified and holds a column number, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Request Body: A JSON array of JSON objects each containing the search field and its search pattern: e.g.:<br />
<code>[{"col": 612, "pattern": "Joe"}, {"col": 614, "pattern": "Tuesday"}]</code> Supported values for <code>col</code> are 603 to 607 (from, to, cc, bcc and subject) and -1 for full text search.<br />
<br />
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get a list of mails ===<br />
<br />
PUT <code>/ajax/mail?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for mails are defined in [[#DetailedMailData | Detailed mail data]].<br />
* <code>headers</code> - (preliminary) A comma-separated list of header names. Each name requests denoted header from each mail<br />
<br />
Request body: An array with one object for each requested mail. Each object contains the fields <code>folder</code> and <code>id</code>.<br />
<br />
Response (not IMAP: with timestamp): An array with mail data. Each array element describes one mail and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter followed by requested headers.<br />
<br />
=== Copy mails ===<br />
<br />
PUT <code>/ajax/mail?action=copy</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested mail.<br />
* <code>folder</code> – Object ID of the source folder.<br />
<br />
Request Body: A JSON object containing the id of the destination folder inside the "folder_id" field: e.g.:<br />
<code>{"folder_id": 1376}</code><br />
<br />
Response: A JSON array containing the ID of the copied mail<br />
<br />
=== Move mails ===<br />
<br />
PUT <code>/ajax/mail?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested mail.<br />
* <code>folder</code> – Object ID of the source folder.<br />
<br />
Request Body: A JSON object containing the id of the destination folder inside the "folder_id" field: e.g.:<br />
<code>{"folder_id": 1376}</code><br />
<br />
<br />
Response: A JSON array containing the ID of the moved mail<br />
<br />
=== Update mails ===<br />
<br />
PUT <code>/ajax/mail?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested mail.<br />
* <code>message_id</code> – (Preliminary) The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.<br />
* <code>folder</code> – Object ID of the folder.<br />
<br />
'''Note''': If neither parameter "<code>id</code>" nor parameter "<code>message_id</code>" is specified, all folder's messages are updated accordingly. Available with v6.20.<br />
<br />
Request Body: A JSON object which carries the new values that ought to be applied to mail as described in [[#UpdateMail | Update mail]] or [[#UpdateMailExtended | Update mail extended]] (available with SP6 v6.10).<br />
<br />
Response: A JSON object containing the Object ID of the updated mail and its folder.<br />
<br />
{| id="UpdateMail" cellspacing="0" border="1"<br />
|+ align="bottom" | Update mail<br />
! Name !! Type !! Value<br />
|-<br />
| color_label || Number || The color number between 0 and 10.<br />
|-<br />
| flags || Number || A set of flags to add or remove. Note: Flags for "recent" (8) and "user" (64) are ignored.<br />
|-<br />
| value || Boolean || <code>true</code> to add the flags specified by <code>flags</code> (logical OR), <code>false</code> to remove them (logical AND with the inverted value).<br />
|}<br />
<br />
<br />
<br />
{| id="UpdateMailExtended" cellspacing="0" border="1"<br />
|+ align="bottom" | Update mail extended (available with SP6 v6.10)<br />
! Name !! Type !! Value<br />
|-<br />
| set_flags || Number || A set of flags to add. Note: Flags for "recent" (8) and "user" (64) are ignored.<br />
|-<br />
| clear_flags || Number || A set of flags to remove. Note: Flags for "recent" (8) and "user" (64) are ignored.<br />
|}<br />
<br />
<br />
=== Mark all mails as seen (available with v7.6.0) ===<br />
<br />
PUT <code>/ajax/mail?action=all_seen</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder.<br />
<br />
Request Body: n.a.<br />
<br />
Response: <code>true</code><br />
<br />
=== Not IMAP: Get updated mails ===<br />
<br />
GET <code>/ajax/mail?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: Just an empty JSON array is going to be returned since this action cannot be applied to IMAP.<br />
<br />
=== Get a mail ===<br />
<br />
GET <code>/ajax/mail?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested mail.<br />
* <code>message_id</code> – (Preliminary) The value of "Message-Id" header of the requested mail. This parameter is a substitute for "id" parameter.<br />
* <code>folder</code> – Object ID of the mail's folder.<br />
* <code>edit</code> (optional) – 1 indicates that this request should fill the message compose dialog to edit a message and thus display-specific date is going to be withheld.<br />
* <code>hdr</code> (optional) – 1 to let the response contain only the (formatted) message headers as plain text<br />
* <code>src</code> (optional) – 1 to let the response contain the complete message source as plain text<br />
* <code>save</code> (optional) – 1 to write the complete message source to output stream. '''NOTE:''' This parameter will only be used if parameter <code>src</code> is set to 1.<br />
* <code>view</code> (optional - available with SP4)<br />
** "raw" returns the content as it is, meaning no preparation are performed and thus no guarantee for safe contents is given (available with SP6 v6.10).<br />
** "text" forces the server to deliver a text-only version of the requested mail's body, even if content is HTML.<br />
** "textNoHtmlAttach" is the same as "text", but does not deliver the HTML part as attachment in case of multipart/alternative content.<br />
** "html" to allow a possible HTML mail body being transferred as it is (but white-list filter applied).<br />
** "noimg" to allow a possible HTML content being transferred but without original image src attributes which references external images: Can be used to prevent loading external linked images (spam privacy protection).<br />
** '''NOTE:''' if set, the corresponding gui config setting will be ignored.<br />
* <code>unseen</code> (optional) – "1" or "true" to leave an unseen mail as unseen although its content is requested<br />
* <code>max_size</code> (optional - available since v7.6.1) A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.<br />
* <code>attach_src</code> (optional - available since v7.6.1) 1 to let the JSON mail representation being extended by <code>"source"</code> field containing the mail raw RFC822 source data<br />
<br />
Response (not IMAP: with timestamp): An JSON object containing all data of the requested mail. The fields of the object are listed in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included. '''NOTE:''' Of course response is not a JSON object if either parameter <code>hdr</code> or parameter <code>src</code> are set to "1". Then the response contains plain text. Moreover if optional parameter <code>save</code> is set to "1" the complete message source is going to be directly written to output stream to open browser's save dialog.<br />
<br />
=== Get multiple mails as a ZIP file ===<br />
<br />
GET <code>/ajax/mail?action=zip_messages</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – The folder identifier.<br />
* <code>id</code> – A comma-separated list of Object IDs of the requested mails<br />
<br />
Response body: The raw byte data of the ZIP file.<br />
<br />
=== Get a mail attachment ===<br />
<br />
GET <code>/ajax/mail?action=attachment</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – The folder identifier.<br />
* <code>id</code> – Object ID of the mail which contains the attachment.<br />
* <code>attachment</code> – ID of the requested attachment '''OR'''<br />
* <code>cid</code> – Value of header 'Content-ID' of the requested attachment<br />
* <code>save</code> – 1 overwrites the defined mimetype for this attachment to force the download dialog, otherwise 0.<br />
* <code>filter</code> (optional) – 1 to apply HTML white-list filter rules if and only if requested attachment is of MIME type <code>text/htm*</code> '''AND''' parameter <code>save</code> is set to 0.<br />
<br />
Response body: The raw byte data of the document. The response type for the HTTP Request is set accordingly to the defined mimetype for this attachment, except the parameter save is set to 1.<br />
<br />
=== Get multiple mail attachments as a ZIP file ===<br />
<br />
GET <code>/ajax/mail?action=zip_attachments</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – The folder identifier.<br />
* <code>id</code> – Object ID of the mail which contains the attachments.<br />
* <code>attachment</code> – A comma-separated list of IDs of the requested attachments<br />
<br />
Response body: The raw byte data of the ZIP file.<br />
<br />
=== Send a mail ===<br />
<br />
POST <code>/ajax/mail?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request Body: This method uses the encoding multipart/form-data or multipart/mixed.<br />
* The form filed <code>json_0</code> contains the rudimentary mail as JSON object as described in [[#DetailedMailData | Detailed mail data]] with just its message body (as html content) defined in nested JSON array "attachments" and its header data (from, to, subject, etc.). The field "content_type" defines whether the mail ought to be sent as plain text ("text/plain"), as html ("text/html") or as multipart/alternative ("ALTERNATIVE"). Sending a mail requires some special fields inside JSON mail object. The field "infostore_ids" defines a JSON array of infostore document ID(s) that ought to be appended to this mail as attachments. The field "msgref" indicates the ID of the referenced original mail. Moreover the field "sendtype" indicates the type of the message:<br />
** 0 - A normal new mail (optional)<br />
** 1 - A reply mail. The field "msgref" must be present<br />
** 2 - A forward mail. The field "msgref" must be present<br />
** 3 - A draft edit operation. The field "msgref" must be present in order to delete previous draft message since e.g. IMAP does not support changing/replacing a message but requires a delete-and-insert sequence<br />
** 4 - Transport of a draft mail. The field "msgref" must be present<br />
** 6 - This type signals that user intends to send out a saved draft message and expects the draft message (referenced by "msgref" field) being deleted after successful transport<br />
Example of a normal new mail which appends user's VCard and requests a read receipt from receiver:<br />
<br />
<code>Content-Disposition: form-data; name="json_0"....{"from":"\u0022Muster, Karl\u0022 <karl.muster@somewhere.com>","to":"someone@somewhere.com","cc":"","bcc":"",<br />
"subject":"Mail Subject","priority":"3","disp_notification_to":true,"vcard":1,<br />
"attachments":[{"content_type":"ALTERNATIVE","content":"Simple Mail Text!&lt;br&gt;&lt;br&gt;\u000a\u000a"}]}</code><br />
* The request accepts file fields in upload form that denote referenced files that are going to be appended as attachments<br />
* For "text/plain" mail bodies, the JSON boolean field "raw" may be specified inside the body's JSON representation to signal that the text content shall be kept as-is; meaning to keep all formatting intact<br />
<br />
==== Attach data sources ====<br />
Moreover the JSON representation may contain data sources which should be appended as file attachments to the mail. Then the mail contains the <code>"datasources"</code> key which is expected to be a JSON array of data source descriptions.<br />
<br />
A data source description follows the [[#Module_.22conversion.22_.28preliminary.29 | conversion specification]].<br />
<br />
For example to attach a file through an URL the field looks like this (available with v6.18.2):<br />
<br />
<pre><br />
{<br />
"from": "someone@somewhere.com,<br />
...<br />
"datasources"<br />
[<br />
{<br />
"identifier": "com.openexchange.url.mail.attachment",<br />
"args":<br />
{<br />
"url": <url-string>,<br />
"timeout": <optional-timeout-millis-int, default is 2500msec>,<br />
"contentType": <optional-content-type-string>,<br />
"charset": <optional-charset-string>,<br />
"size": <optional-size-int>,<br />
"disposition": <optional-disposition-string>,<br />
"fileName": <optional-file-name-string>,<br />
}<br />
}<br />
]<br />
}<br />
</pre><br />
<br />
Response: Object ID of the newly created mail.<br />
<br />
=== Send/Save mail as MIME data block (RFC822) (added in SP5) ===<br />
<br />
PUT <code>/ajax/mail?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>folder</code> (optional) - In case the mail should not be sent out, but saved in a specific folder, the "folder" parameter can be used. If the mail should be sent out to the recipient, the "folder" parameter must not be included and the mail is stored in the folder "Sent Items". Example "folder=default.INBOX/Testfolder"<br />
* <code>flags</code> (optional) - In case the mail should be stored with status "read" (e.g. mail has been read already in the client inbox), the parameter "flags" has to be included. If no "folder" parameter is specified, this parameter must not be included. For infos about mail flags see [[#DetailedMailData | Detailed mail data]] spec.<br />
<br />
Request Body: The MIME Data Block<br />
<br />
Response: Object ID of the newly created/moved mail.<br />
<br />
=== Import of mails as MIME data block (RFC822) (added with 6.18) ===<br />
<br />
This request can be used to store a single or a lot of mails in the OX mail storage backend. This action should be used instead of <code>action=new</code> because it is faster and tolerant to 8bit encoded emails.<br />
<br />
<code>POST /ajax/mail?action=import</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>folder</code> - For the import this parameter is required to specify the folder into that the emails should be imported. Example "folder=default.INBOX/Testfolder"<br />
* <code>flags</code> (optional) - In case the mail should be stored with status "read" (e.g. mail has been read already in the client inbox), the parameter "flags" has to be included. For infos about mail flags see [[#DetailedMailData | Detailed mail data]] spec.<br />
*<code>force</code> (optional) - If this parameter is set to true, the server skips checking the valid From-address<br />
<br />
Request Body: A multipart/form-data with a single or multiple file parts each having a different name and containing the RFC822 encoded email as binary data like in a file upload.<br />
<br />
Response: A JSON object containing the folder identifier and the object identifier of the imported mail or a JSON array of those JSON objects if multiple mails are imported.<br />
<br />
=== Reply/Forward a mail ===<br />
<br />
GET <code>/ajax/mail?action=reply</code><br><br />
GET <code>/ajax/mail?action=replyall</code><br><br />
GET <code>/ajax/mail?action=forward</code><br><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested Message.<br />
* <code>folder</code> - Object ID of the folder, whose contents are queried.<br />
* <code>view</code> (optional - available with SP6) - "text" forces the server to deliver a text-only version of the requested mail's body, even if content is HTML. "html" to allow a possible HTML mail body being transferred as it is (but white-list filter applied).'''NOTE:''' if set, the corresponding gui config setting will be ignored.<br />
* <code>setFrom</code> (optional - available since v7.6.0) A flag ("true"/"false") that signals if "From" header shall be pre-selected according to a suitable recipient address that matches one of user's E-Mail address aliases; only supported for <code>/ajax/mail?action=replyall</code> and <code>/ajax/mail?action=reply</code><br />
* <code>max_size</code> (optional - available since v7.6.1) A positive integer number (greater than 10000) to specify how many characters of the message content will be returned. If the number is smaller than 10000 the value will be ignored and 10000 used.<br />
<br />
Response (not IMAP: with timestamp): An object containing all data of the requested mail. The fields of the object are listed in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included.<br />
<br />
=== Delete mails ===<br />
<br />
PUT <code>/ajax/mail?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* Not IMAP: <code>timestamp</code> – Timestamp of the last update of the deleted mails.<br />
<br />
Request body: An array of objects providing folder IDs and object IDs of the deleted mails.<br />
<code><br><br />
[<br><br />
&nbsp;{&nbsp;&quot;folder&quot;:&quot;default0/INBOX&quot;,&nbsp;&quot;id&quot;:&quot;123&quot;&nbsp;}<br><br />
&nbsp;...<br><br />
&nbsp;{&nbsp;&quot;folder&quot;:&quot;default0/MyFolder&quot;,&nbsp;&quot;id&quot;:&quot;134&quot;&nbsp;}<br><br />
]<br><br />
</code><br />
<br />
Not IMAP: Response: An array with object IDs of mails which were modified after the specified timestamp and were therefore not deleted.<br />
<br />
=== Clear mail folder(s) ===<br />
<br />
PUT <code>/ajax/mail?action=clear</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* Not IMAP: <code>timestamp</code> – Timestamp of the last update of the deleted mails.<br />
<br />
Request body: An array with IDs of the mail folders to clear<br />
<br />
Response: An array with IDs of mail folder that could not be cleared; meaning the response body is an empty JSON array if everything went well.<br />
<br />
== Module "groups" ==<br />
<br />
The group module allows to query available groups. It is mainly used by the dialog for the selection of participants.<br />
<br />
=== Get a group ===<br />
<br />
GET <code>/ajax/group?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The group id.<br />
<br />
Response: A group object as described in [[#GroupData | Group data]].<br />
<br />
=== List groups ===<br />
<br />
PUT <code>/ajax/group?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: An array with group identifiers.<br />
<br />
Response: An array of group objects as described in [[#GroupData | Group data]].<br />
<br />
=== Search for groups ===<br />
<br />
PUT <code>/ajax/group?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: An object with search parameters as described in [[#GroupSearch | Group search]].<br />
<br />
{| id="GroupSearch" cellspacing="0" border="1"<br />
|+ align="bottom" | Group search<br />
! Name !! Type !! Value<br />
|-<br />
| pattern || String || Search pattern to find groups. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.<br />
|}<br />
<br />
Response with timestamp: An array of group objects as described in [[#GroupData | Group data]].<br />
<br />
{| id="GroupData" cellspacing="0" border="1"<br />
|+ align="bottom" | Group data<br />
! Name !! Type !! Value<br />
|-<br />
| id || Number || ID<br />
|-<br />
| display_name || String || Display name<br />
|-<br />
| name || String || Name with character restrictions<br />
|-<br />
| members || Array || The array contains identifier of users that are member of the group.<br />
|}<br />
<br />
=== Create a group ===<br />
<br />
introduced 2008-06-12<br />
<br />
PUT <code>/ajax/group?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: Group object as described in [[#GroupData | Group data]]. The field id is not present.<br />
<br />
Response: A json objekt with attribute <code>id</code> of the newly created group.<br />
<br />
=== Delete a group ===<br />
<br />
introduced 2008-06-12<br />
<br />
PUT <code>/ajax/group?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the group to delete.<br />
<br />
Request body: An object with the field “id” containing the unique identifier of the group.<br />
<br />
Response: An empty json array if the group was deleted successfully.<br />
<br />
=== Change a group ===<br />
<br />
introduced 2008-06-12<br />
<br />
PUT <code>/ajax/group?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the group to update.<br />
* <code>timestamp</code> – Time stamp of the group to update. If the group was modified after the specified time stamp, then the update must fail. <br />
<br />
Request body: Group object as described in [[#GroupData | Group data]]. Only modified fields are present and the field id is omitted.<br />
<br />
=== Get updates (since v6.18.1) ===<br />
<br />
introduced 2010-09-13<br />
<br />
GET <code>/ajax/group?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the requested groups.<br />
<br />
Response with timestamp: An array with new, modified and deleted groups. New, modified and deleted groups are represented by JSON objects as described in [[#GroupData | Group data]].<br />
<br />
== Module "resource" ==<br />
<br />
The resource module allows to query available resources. It is mainly used by the dialog for the selection of participants.<br />
<br />
=== Get all resources ===<br />
<br />
GET <code>/ajax/resource?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: An array of resource identifier.<br />
<br />
=== List resources ===<br />
<br />
PUT <code>/ajax/resource?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
<br />
Request body: An array with resources ids.<br />
<br />
Response: An array of resource objects as described in [[#ResourceResponse | Resource response]].<br />
<br />
=== Get a resource ===<br />
<br />
GET <code>/ajax/resource?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The resource id.<br />
<br />
Response: An array of resource objects as described in [[#ResourceResponse | Resource response]].<br />
<br />
=== Search for resources ===<br />
<br />
PUT <code>/ajax/resource?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: An object with search parameters as described in [[#ParticipantSearch | Participant search]].<br />
<br />
{| id="ParticipantSearch" cellspacing="0" border="1"<br />
|+ align="bottom" | Participant search<br />
! Name !! Type !! Value<br />
|-<br />
| pattern || String || Search pattern to find resources. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.<br />
|}<br />
<br />
Response: An array of resource objects as described in [[#ResourceResponse | Resource response]].<br />
<br />
{| id="ResourceResponse" cellspacing="0" border="1"<br />
|+ align="bottom" | Resource Response<br />
! Name !! Type !! Value<br />
|-<br />
| id || Number || ID<br />
|-<br />
| display_name || String || Display name<br />
|-<br />
| name || String || internal name<br />
|-<br />
| mailaddress || String || email address<br />
|-<br />
| availability || Boolean || can be false to mark the resource currently unavailable<br />
|-<br />
| description || String || description of the resource<br />
|-<br />
| last_modified || Time || Date and time of the last modification.<br />
|-<br />
| last_modified_utc || Timestamp || Date and time of the last modification.<br />
|}<br />
<br />
=== Create a resource ===<br />
<br />
PUT <code>/ajax/resource?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: Resource object as described in [[#ResourceResponse | Resource response]]. The field id is not present.<br />
<br />
Response: An object with attribute <code>id</code> of the newly created resource.<br />
<br />
=== Delete a resource ===<br />
<br />
PUT <code>/ajax/resource?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the resource to delete.<br />
<br />
Request body: An object with the field “id” containing the unique identifier of the resource.<br />
<br />
Response: An empty json array if the resource was deleted successfully.<br />
<br />
=== Delete resources (since v6.22) ===<br />
<br />
PUT <code>/ajax/resource?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the resource to delete.<br />
<br />
Request body: An array of objects with the field “id” containing the unique identifier of the resource.<br />
<br />
Response: An empty json array if the resources were deleted successfully.<br />
<br />
=== Change a resource ===<br />
<br />
PUT <code>/ajax/resource?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the resource to update.<br />
* <code>timestamp</code> – Time stamp of the resource to update. If the resource was modified after the specified time stamp, then the update must fail. <br />
<br />
Request body: Resource object as described in [[#ResourceResponse | Resource response]]. Only modified fields are present and the field id is omitted.<br />
<br />
=== Get updates (since v6.18.1) ===<br />
<br />
introduced 2010-09-13<br />
<br />
GET <code>/ajax/resource?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the requested resources.<br />
<br />
Response with timestamp: An array with new, modified and deleted resources. New, modified and deleted resources are represented by JSON objects as described in [[#ResourceResponse | Resource response]].<br />
<br />
== Module "infostore" or "Filestore" or "Files" or "Drive" ==<br />
This module has been renamed quite often. Whatever its name, it combines the knowledge database, bookmarks and document storage.<br />
<br />
=== Get all infoitems ===<br />
<br />
GET <code>/ajax/infostore?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
{| id="DetailedInfoitemData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed infoitem data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 700 || title || String || Title<br />
|-<br />
| 701 || url || String || Link/URL<br />
|-<br />
| 702 || filename || String || Displayed filename of the document.<br />
|-<br />
| 703 || file_mimetype || String || MIME type of the document. The client converts known types to more readable names before displaying them.<br />
|-<br />
| 704 || file_size || Number || Size of the document in bytes.<br />
|-<br />
| 705 || version || Number || Version number of the document. New documents start at 1. Every update increments the version by 1.<br />
|-<br />
| 706 || description || String || Description<br />
|-<br />
| 707 || locked_until || Time || The time until which this item will presumably be locked. Only set if the docment is currently locked, 0 otherwise.<br />
|-<br />
| 708 || file_md5sum || String || MD5Sum of the document. Not yet implemented, so this is currently always empty.<br />
|-<br />
| 709 || version_comment || String || A version comment is used to file a changelog for the file.<br />
|-<br />
| 710 || current_version || Boolean || “true” if this version is the current version “false” otherwise. . Note: This is not writeable<br />
|-<br />
| 711 || number_of_versions || Number || The number of all versions of the infoitem. Note: This is not writeable.<br />
|}<br />
<br />
=== Get a list of infoitems ===<br />
<br />
PUT <code>/ajax/infostore?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].<br />
<br />
Request body: An array with object IDs of requested infoitems.<br />
<br />
Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get updated infoitems ===<br />
<br />
GET <code>/ajax/infostore?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>timestamp</code> – Timestamp of the last update of the requested infoitems.<br />
* <code>ignore</code> (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.<br />
<br />
Response with timestamp: An array with new, modified and deleted infoitems. New and modified infoitems are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted infoitems (should the <code>ignore</code> parameter be ever implemented) would be identified by their object IDs as plain strings, without being part of a nested array.<br />
<br />
=== Get an infoitem ===<br />
<br />
GET <code>/ajax/infostore?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested infoitem.<br />
* <code>version</code> (optional) – If present the infoitem data describes the given version. Otherwise the current version is returned <br />
<br />
Response with timestamp: An object containing all data of the requested infoitem. The fields of the object are listed in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included.<br />
<br />
=== Search infoitems ===<br />
<br />
PUT <code>/ajax/infostore?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – The requested fields as per tables [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>start</code> (optional) – The start index (inclusive) in the ordered search, that is requested.<br />
* <code>end</code> (optional) – The last index (inclusive) from the ordered search, that is requested.<br />
<br />
Request body: An Object as described in [[#SearchContacts | Search contacts]].<br />
<br />
=== Get an infoitem document ===<br />
<br />
GET <code>/ajax/infostore/[filename]?action=document</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested infoitem.<br />
* <code>folder</code> – Object ID of the infoitem's folder.<br />
* <code>version</code> (optional) – If present the infoitem data describes the given version. Otherwise the current version is returned <br />
* <code>content_type</code>(optional) – If present the response declares the given content_type in the Content-Type header.<br />
<br />
Response body: The raw byte data of the document. The response type for the HTTP Request is set accordingly to the defined mimetype for this infoitem or the content_type given.<br />
<br />
Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.<br />
<br />
=== Get a ZIP archive containing the infoitems of a denoted folder (available with v7.6.1) ===<br />
<br />
GET <code>/ajax/infostore/[filename]?action=document</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the infoitem's folder.<br />
* <code>recursive</code> – <code>true</code> to also include subfolders and their infoitems respectively; otherwise <code>false</code> to only consider the infoitems of specified folder<br />
<br />
Response body: The raw byte data of the ZIP archive. The response type for the HTTP Request is set to <code>application/zip</code>.<br />
<br />
=== Get all versions ===<br />
<br />
GET <code>/ajax/infostore?action=versions</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the infoitem whose versions are requested.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for infoitems are defined in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Response with timestamp: An array with infoitem data. Each array element describes one infoitem and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. The timestamp is the timestamp relating to the requested infostore item.<br />
<br />
=== Get multiple documents as a ZIP archive (available with v7.4.0) ===<br />
<br />
GET <code>/ajax/infostore?action=zipdocuments</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>body</code> – A URL-encoded JSON array; see below for details<br />
<br />
Parameter <code>body</code>: A JSON array of JSON object tuples specifying the documents' versions to include in the requested ZIP archive; e.g<br><br />
<pre><br />
[{"id":"61820","folder":"70303"},{"id":"61821","folder":"70303", "version": "1"}]<br />
</pre><br />
The field <code>"version"</code> is optional; if missing it refers to latest/current version.<br><br />
So, a valid parameter would look like:<br />
<pre><br />
...&body=%5B%7B%22id%22%3A%2261820%22%2C%22folder%22%3A%2270303%22%7D%2C%7B%22id%22%3A%2261821%22%2C%22folder%22%3A%2270303%22%2C%22version%22%3A%221%22%7D%5D<br />
</pre><br />
<br />
Response: The download offer for the requested ZIP archive containing specified document versions<br />
<br />
=== Update an infoitem via PUT ===<br />
<br />
PUT <code>/ajax/infostore?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the updated infoitem.<br />
* <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.<br />
<br />
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.<br />
<br />
=== Update an infoitem via POST ===<br />
<br />
POST <code>/ajax/infostore?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the updated infoitem.<br />
* <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.<br />
* <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.<br />
* <code>file</code> – File Metadata as per <input type=”file” /><br />
<br />
Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.<br />
<br />
Response: The response is sent as a HTML document (see introduction).<br />
<br />
=== Create an infoitem via PUT ===<br />
<br />
PUT <code>/ajax/infostore?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included.<br />
<br />
Response: Object ID of the newly created infoitem.<br />
<br />
=== Create an infoitem via POST ===<br />
<br />
POST <code>/ajax/infostore?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included.<br />
* <code>file</code> – File metadata as per <input type=”file” /><br />
<br />
Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.<br />
<br />
Response: Object ID of the newly created infoitem. The response is sent as a HTML document (see introduction).<br />
<br />
=== Save an attachment in the infostore ===<br />
<br />
PUT <code>/ajax/infostore?action=saveAs</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>attached</code> – The Object ID of the Object with the attachment<br />
* <code>folder</code> – The Folder ID of the Object with the attachment<br />
* <code>module</code> – The Module type of the Object with the attachment.<br />
* <code>Attachment</code> – The id of the attachement to save.<br />
<br />
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included. The fields in this infoitem object override values from the attachment. The folder_id must be given.<br />
<br />
Response: Object ID of the newly created infoitem.<br />
<br />
=== Delete infoitems ===<br />
<br />
PUT <code>/ajax/infostore?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – Timestamp of the last update of the deleted infoitems.<br />
* <code>hardDelete</code> - Optional, defaults to \"false\". If set to \"true\", the file is deleted permanently. Otherwise, and if the underlying storage supports a trash folder and the file is not yet located below the trash folder, it is moved to the trash folder.<br />
<br />
Request body: An array with objects to delete. The fields for the object are described in [[#FullIdentifierForAnInfostoreDocument|Full identifier for an infostore document]].<br />
<br />
Response: An array with [[]]. <br />
<br />
{| id="FullIdentifierForAnInfostoreDocument" cellspacing="0" border="1"<br />
|+ align="bottom" | Full identifier for an infostore document<br />
! Name !! Type !! Value<br />
|-<br />
| id || Number || Object ID<br />
|-<br />
| folder || Number || Folder ID<br />
|}<br />
<br />
=== Delete versions of infostore documents ===<br />
<br />
PUT <code>/ajax/infostore?action=detach</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The ID of the base Object<br />
* <code>folder</code> – The Folder of the Object<br />
* <code>timestamp</code> - Timestamp of the infostore object<br />
<br />
Request body: A List of arrays with the version numbers of the infoitems to detach.<br />
<br />
Response: An array with version numbers that were not deleted.<br />
<br />
Note: When the current version of a document is deleted the new current version will be the newest version.<br />
<br />
=== Delete all versions of infostore documents ===<br />
<br />
PUT <code>/ajax/infostore?action=revert</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The ID of the base Object<br />
* <code>folder</code> – The Folder of the Object<br />
* <code>timestamp</code> - Timestamp of the infostore object<br />
<br />
Removes all versions of the infostore document leaving only the base object.<br />
<br />
=== Copy an infostore document via PUT ===<br />
<br />
PUT <code>/ajax/infostore?action=copy</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The ID of the base Object<br />
* <code>folder</code> – The Folder of the Object<br />
* <code>timestamp</code> - Timestamp of the infostore object<br />
<br />
Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.<br />
<br />
Response: The id of the newly created object<br />
<br />
Note: Only the fields (and the file) of the current document will be copied. Those fields present in the request are modified accordingly.<br />
<br />
=== Copy an infostore document via POST ===<br />
<br />
POST <code>/ajax/infostore?action=copy</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the updated infoitem.<br />
* <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.<br />
* <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.<br />
* <code>file</code> – File Metadata as per <input type=”file” /><br />
<br />
Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.<br />
<br />
Response: The response is sent as a HTML document (see introduction).<br />
<br />
Note: Only the fields (and the file) of the current document will be copied. Those fields present in the request are modified accordingly.<br />
<br />
=== Lock an infoitem ===<br />
<br />
GET <code>/ajax/infostore?action=lock</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the infoitem that should be locked.<br />
* <code>diff</code> (optional) – If present the value is added to the current time on the server (both in ms). The document will be locked until that time. If this parameter is not present, the document will be locked for a duration as configured on the server.<br />
<br />
Response with timestamp: Can only include errors.<br />
<br />
=== Unlock an infoitem ===<br />
<br />
GET <code>/ajax/infostore?action=unlock</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the infoitem that should be unlocked.<br />
<br />
Response with timestamp: Can only contain errors.<br />
<br />
<br />
== Module "Attachments" ==<br />
<br />
The Attachment Module allows file attachments to arbitrary objects. An Attachment always belongs to an object (called 'attached') in a certain folder of a certain module. <br />
<br />
=== Get All Attachments for an Object ===<br />
<br />
GET <code>/ajax/attachment?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>attached</code> – The Object ID of the Object<br />
* <code>folder</code> – The Folder ID of the Object<br />
* <code>module</code> – The Module type of the Object<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for attachment's are defined in [[#CommonObjectData | Common object data]] (with only id, created_by and creation_date available) and [[#AttachmentObject | Attachment object]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Response: An array with attachment data. Each array element describes one attachment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get a list of attachments ===<br />
<br />
PUT <code>/ajax/attachment?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for attachments are defined in [[#CommonObjectData | Common object data]] (with only id, created_by and creation_date available) and [[#AttachmentObject | Attachment object]].<br />
* <code>attached</code> – The Object ID of the Object<br />
* <code>folder</code> – The Folder ID of the Object<br />
* <code>module</code> – The Module type of the Object<br />
<br />
Request body: An array of with object IDs of requested tasks.<br />
<br />
Response with timestamp: An array with attachment data. Each array element describes one attachment and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Create an Attachment ===<br />
<br />
POST <code>/ajax/attachment?action=attach</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>json_[index]</code> – The JSON representation of an attachment object as described in [[#CommonObjectData | Common object data]] (with only id, created_by and creation_date available) and [[#AttachmentObject | Attachment object]].<br />
* <code>file_[index]</code> – The file metadata as per <input type=file /> upload.<br />
<br />
Note: The JSON Object and file fields describe the corresponding attachment. For ex.: json_0 contains metadata for file_0, json_1 for file_1 and so on. Indexes start with 0.<br />
<br />
Request body: multipart/form-data or multipart/mixed containing the file data of the attached file and the above fields.<br />
<br />
Response: HTML page with javascript callback as per introduction. Contains a JSON-Array of ids of the newly created attachments. The order of the ids corresponds to the indexes in the request.<br />
<br />
{| id="AttachmentObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Attachment Object<br />
! ID !! Name !! Type !! Description<br />
|-<br />
| 800 || folder || Number || The ID of the first Folder in which the attached object resides.<br />
|-<br />
| 801 || attached || Number || The object id of the object this attachement is attached to.<br />
|-<br />
| 802 || module || Number || The Module of this Object Possible Values:<br />
{| cellspacing="0" border="1"<br />
| 1 || Appointment<br />
|-<br />
| 4 || Task<br />
|-<br />
| 7 || Contact<br />
|-<br />
| 137 || Infostore<br />
|}<br />
|-<br />
| 803 || filename || String || The filename of the attached file.<br />
|-<br />
| 804 || file_size || Number || The file size (in bytes) of the attached file.<br />
|-<br />
| 805 || file_mimetype || String || The MIME-Type of the attached file<br />
|-<br />
| 806 || rft_flag || Boolean || If the attachment is a RTF Attachment of Outlook. (Outlook descriptions can be stored as RTF Documents).<br />
|}<br />
<br />
=== Delete Attachment ===<br />
<br />
PUT <code>/ajax/attachment?action=detach</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>attached</code> – The ID of the base Object<br />
* <code>module</code> – The type of the Object<br />
* <code>folder</code> – The Folder of the Object<br />
<br />
Request body: An array with the ids of the attachments to delete.<br />
<br />
=== Get updated attachments ===<br />
<br />
GET <code>/ajax/attachment?action=updates</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>attached</code> – Object ID of the object to which the attachments are attached.<br />
* <code>module</code> – Module ID (as per [[#AttachmentObject | Attachment object]]) of the attached object.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for attachments are defined in [[#CommonObjectData | Common object data]] (with only id, created_by and creation_date available) and [[#AttachmentObject | Attachment object]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
* <code>timestamp</code> – Timestamp of the last update of the requested infoitems.<br />
ignore (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.<br />
<br />
Response with timestamp: An array with new and deleted attachments for the specified object. New attachments are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted attachments (should the <code>ignore</code> parameter be ever implemented) would be identified by their object IDs as plain numbers, without being part of a nested array.<br />
<br />
=== Get an attachment ===<br />
<br />
GET <code>/ajax/attahment?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>attached</code> – Object ID of the object to which the attachments are attached.<br />
* <code>module</code> – Module ID (as per [[#AttachmentObject | Attachment object]]) of the attached object.<br />
* <code>id</code> – Object ID of the requested attachment.<br />
<br />
Response with timestamp: An object containing all data of the requested attachment. The fields of the object are listed in [[#CommonObjectData | Common object data]] (with only id, created_by and creation_date available) and [[#AttachmentObject | Attachment object]]. <br />
<br />
=== Get an attachments filedata ===<br />
<br />
GET <code>/ajax/attachment/[filename]?action=document</code><br />
<br />
Parameters:<br />
<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – Object ID of the folder, whose contents are queried.<br />
* <code>attached</code> – Object ID of the object to which the attachments are attached.<br />
* <code>module</code> – Module ID (as per [[#AttachmentObject | Attachment object]]) of the attached object.<br />
* <code>id</code> – Object ID of the requested attachment.<br />
* <code>content_type</code> (optional) – If set the responses Content-Type header is set to this value, not the attachements file mime type.<br />
<br />
Response body: The raw byte data of the document. The response type for the HTTP Request is set accordingly to the defined mimetype for this infoitem.<br />
Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.<br />
<br />
== Module "reminder" ==<br />
<br />
The reminder module provides the ability to fetch all active reminders for a user between two dates.<br />
<br />
=== Get reminder range ===<br />
<br />
GET <code>/ajax/reminder?action=range</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>end</code> – The End date of the reminder range<br />
<br />
Response: An Array with all reminders which are scheduled until the specified time. Each reminder is described in [[#ReminderResponse | Reminder response]].<br />
<br />
{| id="ReminderResponse" cellspacing="0" border="1"<br />
|+ align="bottom" | Reminder response<br />
! Field !! Type !! Description<br />
|-<br />
| id || Number || The ID of the reminder.<br />
|-<br />
| target_id || Number || The target_id where this reminder is attached to<br />
|-<br />
| alarm || Time || The time of the alarm<br />
|-<br />
| module || Number || The module of the reminder<br />
|-<br />
| servertime || Time || The time on the server<br />
|-<br />
| user_id || Number || The ID of the user.<br />
|-<br />
| last_modified || Time || The last modification timestamp of the reminder<br />
|-<br />
| recurrence_position || Number || The recurrence position for series appointments or 0 if no series<br />
|-<br />
| folder || Number || The ID of the folder through that the object can be read<br />
|-<br />
|}<br />
<br />
=== Delete a Reminder===<br />
<br />
PUT <code>/ajax/reminder?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: An object with the field “id”.<br />
<br />
Response body: An JSON array with the id that was not deleted.<br />
<br />
=== Delete Reminders (since v6.22)===<br />
<br />
PUT <code>/ajax/reminder?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: An array of objects with the field “id”.<br />
<br />
Response body: An JSON array with the ids that were not deleted.<br />
<br />
=== Remind again (since v6.18.1) ===<br />
<br />
PUT <code>/ajax/reminder?action=remindAgain</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The ID of the reminder whose date shall be changed.<br />
<br />
Request body: The JSON representation of the reminder; mainly containing the field “alarm” which provides the new reminder date.<br><br />
E.g. <code>{ "alarm": 1283418027381 }</code><br />
<br />
Response body: The JSON representation of the updated reminder.<br />
<br />
== Module "multiple" ==<br />
<br />
The multiple module allows to bundle multiple requests to most other modules in a single request. Not supported are:<br />
* modules login and multiple,<br />
* POST requests with a multipart encoding (uploads),<br />
* GET requests which do not use an object as described in [[#ResponseBody | Response body]] as response body (downloads).<br />
<br />
=== Multiple requests ===<br />
<br />
PUT <code>/ajax/multiple</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>continue</code> – Specifies whether processing of requests should stop when an error occurs, or whether all request should be processed regardless of errors.<br />
<br />
Request body: An array with request objects. Each request object contains all URI parameters of the "normal" request as fields. The module name of the "normal" request is included in the field module. The parameter session is not included. If the "normal" request has a request body, the object which is represented by that request body is includes as the value of the field data.<br />
<br />
Response: An array with reply objects as described in [[#ResponseBody | Response body]]. The order of reply objects corresponds to the order of requests in the request body. Unlike with all other modules, this response is itself not part of a response object as described in [[#ResponseBody | Response body]].<br />
<br />
== Module "quota" ==<br />
<br />
The filestore module allows accesssing information about the use and quota of the filestore.<br />
<br />
=== Get quota information (Since 7.6.1, Preliminary) ===<br />
<br />
GET <code>/ajax/quota?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>module</code> (optional) – The module identifier to get quota information for, required if <code>account</code> is set.<br />
* <code>account</code> (optional) – The account identifier within the module to get quota information for.<br />
<br />
Response: A JSON object containing the requested quota information. If no <code>module</code> was specified, all defined [[#ModuleQuota | module quotas]] are set in the JSON object, each one mapped to it's module identifier. If the quota from a <code>module</code> was requested, a JSON array containing all [[#AccountQuota | account quotas]] of this module are returned. If both a <code>module</code> and <code>account</code> were requested, a JSON object representing this specific [[#AccountQuota | account auota]] is returned. <br />
<br />
Note: In case there is no quota limitation defined for a module or account, no corresponding JSON object is included in the response. <br />
<br />
<br />
{| id="ModuleQuota" cellspacing="0" border="1"<br />
|+ align="bottom" | Module Quota<br />
! Field !! Type !! Description<br />
|-<br />
| display_name || String || The display name of the module<br />
|-<br />
| accounts|| Array || Each element identifies an account quota within the module, as described in [[#AccountQuota | Account Quota]]<br />
|-<br />
|}<br />
<br />
<br />
{| id="AccountQuota" cellspacing="0" border="1"<br />
|+ align="bottom" | Account Quota<br />
! Field !! Type !! Description<br />
|-<br />
| account_id || String || Identifier of the account<br />
|-<br />
| account_name || String || Name of the account<br />
|-<br />
| countquota || Number || The account's quota limit for the number of items, or not set if not defined<br />
|-<br />
| countuse || Number || The account's actual usage for the number of items, or not set if no count quota defined<br />
|-<br />
| quota || Number || The account's quota limit for the storage in bytes, or not set if not defined<br />
|-<br />
| use || Number || The account's actual usage for the storage in bytes, or not set if no storage quota defined<br />
|-<br />
|}<br />
<br />
<br />
=== Get the filestore usage data ===<br />
<br />
GET <code>/ajax/quota?action=filestore</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON Object containing the fields “use” and “quota”. “use” represents the uploaded files sizes sum and the field “quota” represents the maximum.<br />
<br />
=== Get the mail usage data ===<br />
<br />
GET <code>/ajax/quota?action=mail</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON Object containing the fields “use” and “quota”. “use” represents the use mail quota and the field “quota” represents the maximum. -1 represents an unlimited quota.<br />
<br />
== Module "import"==<br />
The module import allows to import specific module data (like Contacts, Tasks or Appointments) in several formats (iCal, vCard, CSV) into a folder. Please note: The callback for all actions of this bundle is callback_import, not callback_$actionname for legacy purposes.<br />
<br />
=== Import CSV ===<br />
POST <code>/ajax/import?action=CSV</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.<br />
<br />
Request body: A "multipart/form-data" encoded .CSV file. The field name for the file is "file". The column titles of the table are those used within the OX, see column ''Displayed Name'' in [[#DetailedContactData]].<br />
<br />
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered.<br />
<br />
=== Import Outlook CSV ===<br />
POST <code>/ajax/import?action=OUTLOOK_CSV</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.<br />
<br />
Request body: An .CSV file with Windows' default encoding Windows-1252. The column titles of the table may be those used by the English, French or German version of Outlook.<br />
<br />
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered.<br />
<br />
=== Import iCAL ===<br />
POST <code>/ajax/import?action=ICAL</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ObjectID of the folder into which data should be imported. This may be an Appointment or a Task folder. May even be a list containing both.<br />
* <code>suppressNotification</code> – This optional parameter can be used to disable the notifications for new appointments that are imported through the given iCal file. This help keeping the Inbox clean if a lot of appointments need to be imported. The value of this parameter does not matter because only for the existence of the parameter is checked.<br />
* <code>ignoreUIDs</code> – Optional. When set to "true", UIDs are partially ignored during import of tasks and appointments from iCal. Internally, each UID is replaced statically by a random one to preserve possibly existing relations between recurring appointments in the same iCal file, but at the same time to avoid collisions with already existing tasks and appointments.<br />
<br />
Request body: An iCalendar file.<br />
<br />
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered, and warnings (under the key "warnings") containing an Array of objects with the warning data, containing all customary error fields.<br />
<br />
=== Import vCard ===<br />
POST <code>/ajax/import?action=VCARD</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.<br />
<br />
Request body: An vCard file, maybe of the formats: vCard 2.1, vCard 3.0 or vCalendar 1.0<br />
<br />
Response: An array of JSON-Objects, one for each entry in the list, containing: The Object ID of the entry, the Object ID of the folder the data was written into, a timestamp of the modification (in case of error, of modification attempt) and an error in case the data could not be entered.<br />
<br />
== Module "export" ==<br />
The module export allows to export specific module data (like Contacts, Tasks or Appointments) from a folder in several formats (iCal, vCard, CSV).<br />
<br />
=== Exporting CSV ===<br />
GET <code>/ajax/export?action=CSV</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Contact folder.<br />
* <code>columns</code> – (optional) Columns to be imported from the given file, given as an array of column numbers. See [[#DetailedContactData | Detailed contact data]] for numbers.<br />
* <code>export_dlists</code> – (optional) toggles whether distribution lists are exported, too. Default is false. Option exists since 7.4.1.<br />
Response: An InputStream containing the file of the MIME type <code>text/csv</code>.<br />
<br />
=== Exporting iCAL ===<br />
GET <code>/ajax/export?action=ICAL</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Calendar folder.<br />
<br />
Response: An InputStream containing the file, of the MIME type <code>text/calendar</code>.<br />
<br />
=== Exporting vCard ===<br />
GET <code>/ajax/export?action=VCARD</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Contact folder.<br />
<br />
Response: An InputStream containing the file, of the MIME type <code>text/x-vcard</code>.<br />
<br />
== Module "sync" ==<br />
The module sync delivers several core API extensions to support common operations used in a mobile synchronization environment.<br />
<br />
=== Clearing a folder's content ===<br />
PUT <code>/ajax/sync?action=refresh_server</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON array containing the folder ID(s) whose content should be cleared. '''NOTE:''' Although the requests offers to clear multiple folders at once it is recommended to clear only one folder per request since if any exception occurs<br />
(e.g. missing permissions) the complete request is going to be aborted.<br />
<br />
Response: A JSON array containing the IDs of folders that could not be cleared due to a concurrent modification. Meaning you receive an empty JSON array if everything worked well.<br />
<br />
== Module "token" (since 7.4.0) ==<br />
The module token delivers several core API extensions to support token based logins.<br />
<br />
=== Get a login token ===<br />
GET <code>/ajax/token?action=acquireToken</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response:<br />
A JSON object with the timestamp of the creation date and a token which can be used to create a new session.<br />
<br />
== Module "mailfilter" ==<br />
The module mailfilter describes how to add, update or delete mail filter rules or to check which actions are supported by the underlying system.<br />
<br />
A detailed description can be found here [[ HTTP_API_MailFilter | Mail Filter HTTP API]]<br />
<br />
== Module "ajax file upload" ==<br />
This module offers to store files in server's dedicated download directory for a configureable amount of time. The files are then accessible for further operations like inline images in (html) mails<br />
<br />
=== Uploading a file ===<br />
POST <code>/ajax/file?action=new</code> <br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>module</code> – The module for which the file is uploaded to determine proper upload quota constraints (e.g. "mail", "infostore", etc.).<br />
* <code>type</code> – The file type filter to define which file types are allowed during upload. Currently supported filters are: <code>file=all, text=text/*, media=image OR audio OR video, image=image/*, audio=audio/*, video=video/*, application=application/*</code><br />
<br />
Request body: A common POST request body of MIME type "multipart/*" which holds the file(s) to upload<br />
<br />
Response: A JSON array containing the IDs of the uploaded files. The files are accessible through the returned IDs for future use.<br />
<br />
=== Updating a file's last access timestamp (keep alive) ===<br />
By updating the last access timestamp it's prevented from being deleted from both session and disk storage.<br />
<br />
GET <code>/ajax/file?action=keepalive</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The ID of the uploaded file whose timestamp should be updated<br />
<br />
Response: The string "null" in response's data element<br />
<br />
=== Requesting a formerly uploaded file ===<br />
GET <code>/ajax/file?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The ID of the uploaded file<br />
<br />
Response: The content of the requested file is directly written into output stream<br />
<br />
== Module "image" ==<br />
This module allows to download images from Open-Xchange server without providing a session ID in request's URL parameters.<br />
<br />
=== Requesting an image ===<br />
Open-Xchange Server supports multiple image sources that are identified through request's path identifier<br />
<br />
* Inline images from mails<br />
** Request path needs to be <code>"/mail/picture"</code><br><br><br />
* Contact profile image<br />
** Request path needs to be <code>"/contact/picture"</code><br><br><br />
* User profile image<br />
** Request path needs to be <code>"/user/picture"</code><br><br><br />
* MP3 cover image<br />
** Request path needs to be <code>"/file/mp3cover"</code><br><br><br />
* Fetch a previously uploaded image using <code>"/ajax/file"</code> interface<br />
** Request path needs to be <code>"/mfile/picture"</code><br><br><br />
<br />
Each image source requires an individual set of required parameters<br />
<br />
==== Inline images from mails ====<br />
GET <code>/mail/picture</code> <br />
<br />
Parameters:<br />
* <code>accountId</code> – The mail account identifier<br />
* <code>folder</code> – The identifier of the folder in which the mail resides<br />
* <code>id</code> – The mail identifier<br />
* <code>uid</code> – The identifier of the image inside the referenced mail<br />
<br />
Response: The content of the requested image is directly written into output stream<br />
<br />
<br />
==== Contact profile images ====<br />
GET <code>/contact/picture</code> <br />
<br />
Parameters:<br />
* <code>folder</code> – The identifier of the folder in which the contact resides<br />
* <code>id</code> – The contact identifier<br />
<br />
Response: The content of the requested image is directly written into output stream<br />
<br />
<br />
==== User profile images ====<br />
GET <code>/user/picture</code> <br />
<br />
Parameters:<br />
* <code>id</code> – The user identifier<br />
<br />
Response: The content of the requested image is directly written into output stream<br />
<br />
<br />
==== MP3 cover image ====<br />
GET <code>/file/mp3cover</code> <br />
<br />
Parameters:<br />
* <code>id</code> – The identifier of the uploaded image<br />
<br />
Response: The content of the requested image is directly written into output stream<br />
<br />
== Module "conversion" (preliminary) ==<br />
<br />
A generic module to request data from a data source and to process obtained/submitted data with a data handler. Thus data is converted from a data source by a data handler.<br />
<br />
=== Converting data ===<br />
PUT <code>/ajax/conversion?action=convert</code><br><br />
or<br><br />
POST <code>/ajax/conversion?action=convert</code> <br />
<br />
Parameters: &lt;no parameters required&gt;<br />
<br />
Request body: A [[#ConversionRequest | conversion request]] JSON object containing nested JSON objects for [[#DataSource | data source]] and [[#DataHandler | data handler]]<br />
<br />
<br />
{| id="ConversionRequest" cellspacing="0" border="1"<br />
|+ align="bottom" | Conversion request object<br />
! Field !! Type !! Description<br />
|-<br />
| datasource || JSON object || The data source object.<br />
|-<br />
| datahandler || JSON object || The data handler object.<br />
|-<br />
|}<br />
<br />
<br />
{| id="DataSource" cellspacing="0" border="1"<br />
|+ align="bottom" | Data source object<br />
! Field !! Type !! Description<br />
|-<br />
| identifier || String || The identifier of the data source.<br />
|-<br />
| args || JSON array or JSON object || The '''optional''' name-value-pairs as a single JSON object or a JSON object for each kept inside a JSON array for data source<br />
|-<br />
|}<br />
<br />
<br />
{| id="DataHandler" cellspacing="0" border="1"<br />
|+ align="bottom" | Data handler object<br />
! Field !! Type !! Description<br />
|-<br />
| identifier || String || The identifier of the data handler.<br />
|-<br />
| args || JSON array or JSON object || The '''optional''' name-value-pairs as a single JSON object or a JSON object for each kept inside a JSON array for data handler<br />
|-<br />
|}<br />
<br />
Response: The result of converted data ready as an appropriate JSON response<br />
<br />
==== Saving an ICal email attachment ====<br />
<br />
If an ICal file is attached to an email, its content can be saved as appointments and tasks into given calendar and task folder.<br />
If the fields "com.openexchange.groupware.calendar.confirmstatus" and "com.openexchange.groupware.calendar.confirmmessage" are set, the data handler inserts the appointment with the given status for the user, if the appointment does not exist. If it is already existing, the handler just updates the participant status.<br />
<br />
Data source's JSON object<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.mail.ical&quot;<br><br />
&nbsp;&quot;args&quot;:<br><br />
&nbsp;&nbsp;[<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.fullname&quot;:&quot;&lt;folder-fullname&gt;&quot;},<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.mailid&quot;:&quot;&lt;mail-id&gt;&quot;},<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.sequenceid&quot;:&quot;&lt;attachment-sequence-id&gt;&quot;}<br><br />
&nbsp;&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
Data handler's JSON object<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.ical&quot;<br><br />
&nbsp;&quot;args&quot;:<br><br />
&nbsp;&nbsp;[<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.groupware.calendar.folder&quot;:&quot;&lt;calendar-folder-id&gt;&quot;},<br><br />
&nbsp;&nbsp;<br />
{&quot;com.openexchange.groupware.task.folder&quot;:&quot;&lt;task-folder-id&gt;&quot;},<br><br />
&nbsp;&nbsp;<br />
{&quot;com.openexchange.groupware.calendar.confirmstatus&quot;:&quot;&lt;status&gt;&quot;},<br><br />
&nbsp;&nbsp;<br />
{&quot;com.openexchange.groupware.calendar.confirmmessage&quot;:&quot;&lt;message&gt;&quot;}<br><br />
&nbsp;&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
Response: A JSON array of JSON objects each providing folder and object ID of added appointment/task; e.g. <code>[{&quot;folder_id&quot;:2567, &quot;id&quot;:7689}, ...]</code><br />
<br />
==== Converting an ICal email attachment into JSON objects ====<br />
<br />
If an ICal file is attached to an email, its content can converted to JSON appointments and tasks.<br />
<br />
Data source's JSON object<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.mail.ical&quot;<br><br />
&nbsp;&quot;args&quot;:<br><br />
&nbsp;&nbsp;[<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.fullname&quot;:&quot;&lt;folder-fullname&gt;&quot;}<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.mailid&quot;:&quot;&lt;mail-id&gt;&quot;}<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.sequenceid&quot;:&quot;&lt;attachment-sequence-id&gt;&quot;}<br><br />
&nbsp;&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
Data handler's JSON object.<br><br />
'''Note''' that all arguments are optional: Default is user time zone and zero recurrence position<br><br />
"com.openexchange.groupware.calendar.searchobject" triggers a search for the uid, and replaces the object_id and folder_id with the data of the corresponding ox-object id, if existing. The returned objects are still the ical objects and NOT the ox-objects.<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.ical.json&quot;<br><br />
&nbsp;&quot;args&quot;:<br><br />
&nbsp;&nbsp;[<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.groupware.calendar.timezone&quot;:&quot;&lt;timezone-id&gt;&quot;}<br><br />
&nbsp;&nbsp;<br />
{&quot;com.openexchange.groupware.calendar.recurrencePosition&quot;:&quot;&lt;recurrence-position&gt;&quot;}<br><br />
&nbsp;&nbsp;<br />
{&quot;com.openexchange.groupware.calendar.searchobject&quot;:&quot;&lt;true|false&gt;&quot;}<br><br />
&nbsp;&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
Response: A JSON array of JSON objects for each appointment/task as described in [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]] and [[##DetailedTaskData | Detailed task data]]/[[##DetailedAppointmentData | Detailed appointment data]]<br />
<br />
==== Saving a VCard email attachment ====<br />
<br />
If a VCard file is attached to an email, its content can be saved as contacts into given contact folder.<br />
<br />
Data source's JSON object<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.mail.vcard&quot;,<br><br />
&nbsp;&quot;args&quot;:<br><br />
&nbsp;&nbsp;[<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.fullname&quot;:&quot;&lt;folder-fullname&gt;&quot;},<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.mailid&quot;:&quot;&lt;mail-id&gt;&quot;},<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.mail.conversion.sequenceid&quot;:&quot;&lt;attachment-sequence-id&gt;&quot;}<br><br />
&nbsp;&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
Data handler's JSON object<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.contact&quot;,<br><br />
&nbsp;&quot;args&quot;:<br><br />
&nbsp;&nbsp;[<br><br />
&nbsp;&nbsp;&nbsp;{&quot;com.openexchange.groupware.contact.folder&quot;:&quot;&lt;contact-folder-id&gt;&quot;}<br><br />
&nbsp;&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
Response: A JSON array of JSON objects each providing folder and object ID of added contact; e.g. <code>[{&quot;folder_id&quot;:2567, &quot;id&quot;:7689}, ...]</code><br />
<br />
==== Contact(s) attached to a new email as a VCard file ====<br />
<br />
Obtain VCard data from specified contact object(s).<br />
<br />
Data source's JSON object<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.contact&quot;<br><br />
&nbsp;&quot;args&quot;:<br><br />
&nbsp;&nbsp;[<br><br />
&nbsp;&nbsp;&nbsp;{&quot;folder&quot;:&quot;&lt;folder-id1&gt;&quot;,&quot;id&quot;:&quot;&lt;id1&gt;&quot;}<br><br />
&nbsp;&nbsp;&nbsp;...<br><br />
&nbsp;&nbsp;&nbsp;{&quot;folder&quot;:&quot;&lt;folder-idn&gt;&quot;,&quot;id&quot;:&quot;&lt;idn&gt;&quot;}<br><br />
&nbsp;&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
Get a new email's JSON object with specified VCard data source attached.<br />
<br />
Data handler's JSON object<br><br />
<code><br />
{<br><br />
&nbsp;&quot;identifier&quot;:&quot;com.openexchange.mail.vcard&quot;<br><br />
&nbsp;&quot;args&quot;:[]<br><br />
}<br><br />
</code><br />
<br />
Response: A [[#DetailedMailData | mail]] JSON object.<br />
<br />
== Module "search" (preliminary) ==<br />
<br />
The search module is an enhancement to each search request as an optional JSON object via PUT method to filter elements; e.g.<br />
<br />
<code><br />
PUT /ajax/contacts?action=all&...<br />
<br />
{"filter":{search-term-object}}<br />
</code><br />
<br />
This section describes the syntax of the optional JSON object representing the search term.<br><br />
In general the structure of a search term is in prefix notation; meaning the operator is written before its operands:<br />
<br />
<code>{"operation":"equals","operands":[...]}</code><br />
<br />
Moreover there are two different types of a search terms:<br />
* A single search term<br />
* A composite search term<br />
<br />
A single search term reflects an operation which cannot hold nested search terms as operands; e.g. "equals". In opposite to this a composite search term holds one or more nested search terms as operands; e.g. "not" or the logical junctors "and"/"or".<br />
<br />
By now the following operations are supported:<br />
* composite operations<br />
** "and" - The AND junctor<br />
** "or" - The OR junctor<br />
** "not" - Negation<br />
* single operations<br />
** "equals" - Equals comparison<br />
** "lt" - Less-than comparison<br />
** "gt" - Greater-than comparison<br />
<br />
Furthermore following operand types are supported for single search terms:<br />
* Column - Providing a name referring to a field/column<br />
* Constant - A constant<br />
<br />
Example of an EQUALS search term:<br><br />
<code><br />
{"operation":"equals","operands":[{"type":"column","value":"first_name"},"Jane"]}<br />
</code><br />
<br />
Example of an OR search term:<br><br />
<code><br />
{"operation":"or","operands":<br><br />
&nbsp;[<br><br />
&nbsp;&nbsp;{"operation":"equals","operands":[{"type":"column","value":"first_name"},"Jane"]},<br><br />
&nbsp;&nbsp;{"operation":"gt","operands":[{"type":"column","value":"birthday"},"1975-05-01"]}<br><br />
&nbsp;]<br><br />
}<br><br />
</code><br />
<br />
<br />
Refer to object data tables introduced by different modules to know which field names are supported; e.g. for tasks it is [[#CommonObjectData | Common object data]], [[#DetailedTaskAndAppointmentData | Detailed task and appointment data]], and [[#DetailedTaskData | Detailed task data]].<br />
<br />
== Module "search" (alternative suggestion, still preliminary) ==<br />
<br />
The search module is an enhancement to each search request as an optional JSON object via PUT method to filter elements; e.g.<br />
<br />
<code><br />
PUT /ajax/contacts?action=all&...<br />
<br />
{"filter":<i>[search term]</i>}<br />
</code><br />
<br />
This section describes the syntax of the optional JSON object representing the search term.<br />
In general the structure of a search term is in prefix notation; meaning the operator is written before its operands:<br />
<br />
<code>[">", 5, 2]</code><br />
<br />
The available operators are:<br />
* Comparison operators ">", "<", "=", "<=", ">=", "<>"<br />
* logic operators "not", "and", "or"<br />
<br />
Comparison operators have exactly two operands. Each operand can be either a field name or a constant. A field name is an object with the member "field" specifying the field name, e.g. <code>{ field: "first_name" }</code>. The available field names depend on the searched module. Primitive JSON types are interpreted as constants. Arrays are not valid operands for comparison operators.<br />
<br />
The logic operator "not" has exactly one operand, the other logic operators can have any number of operands. Each operand must be an array representing a nested search expression.<br />
<br />
== Module "mail account" (available with v6.12) ==<br />
<br />
The mail account module is used to manage multiple mail accounts held by a user.<br />
<br />
=== Get All mail accounts ===<br />
<br />
GET <code>/ajax/account?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for mail account's are defined in [[#MailAccountData | mail account data]].<br />
<br />
Response: An array with attachment data. Each array element describes one mail account and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get a mail account ===<br />
<br />
GET <code>/ajax/account?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The ID of the account to return.<br />
<br />
Response: A JSON object representing the desired mail account. See [[#MailAccountData | mail account data]].<br />
<br />
{| id="MailAccountData" cellspacing="0" border="1"<br />
|+ align="bottom" | Mail account data<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| 1001 || id || Number || Account ID<br />
|-<br />
| 1002 || login || String || The login.<br />
|-<br />
| 1003 || password || String || The (optional) password.<br />
|-<br />
| 1004 || mail_url || String || The mail server URL; e.g. "imap://imap.somewhere.com:143". '''URL is preferred over single fields''' (like mail_server, mail_port, etc.)<br />
|-<br />
| 1005 || transport_url || String || The transport server URL; e.g. "smtp://smtp.somewhere.com:25". '''URL is preferred over single fields''' (like transport_server, transport_port, etc.)<br />
|-<br />
| 1006 || name || String || Account's display name.<br />
|-<br />
| 1007 || primary_address || String || User's primary address in account; e.g. "someone@somewhere.com"<br />
|-<br />
| 1008 || spam_handler || String || The name of the spam handler used by account.<br />
|-<br />
| 1009 || trash || String || The name of the default trash folder.<br />
|-<br />
| 1010 || sent || String || The name of the default sent folder.<br />
|-<br />
| 1011 || drafts || String || The name of the default drafts folder.<br />
|-<br />
| 1012 || spam || String || The name of the default spam folder.<br />
|-<br />
| 1013 || confirmed_spam || String || The name of the default confirmed-spam folder.<br />
|-<br />
| 1014 || confirmed_ham || String || The name of the default confirmed-ham folder.<br />
|-<br />
| 1015 || mail_server || String || The mail server's hostname or IP address.<br />
|-<br />
| 1016 || mail_port || Number || The mail server's port.<br />
|-<br />
| 1017 || mail_protocol || String || The mail server's protocol. '''Always use basic protocol name.''' E.g. use "imap" instead of "imaps"<br />
|-<br />
| 1018 || mail_secure || Boolean || Whether to establish a secure connection to mail server (SSL, TLS).<br />
|-<br />
| 1019 || transport_server || String || The transport server's hostname or IP address.<br />
|-<br />
| 1020 || transport_port || Number || The transport server's port.<br />
|-<br />
| 1021 || transport_protocol || String || The transport server's protocol. '''Always use basic protocol name.''' E.g. use "smtp" instead of "smtps"<br />
|-<br />
| 1022 || transport_secure || Boolean || Whether to establish a secure connection to transport server (SSL, TLS).<br />
|-<br />
| 1023 || transport_login || String || The transport login. '''Please see "transport_auth" for the handling of this field.'''<br />
|-<br />
| 1024 || transport_password || String || The transport password. '''Please see "transport_auth" for the handling of this field.'''<br />
|-<br />
| 1025 || unified_inbox_enabled || Boolean || If enabled for Unified INBOX<br />
|-<br />
| 1026 || trash_fullname || String || Path to default trash folder. Preferred over "trash"<br />
|-<br />
| 1027 || sent_fullname || String || Path to default sent folder. Preferred over "sent"<br />
|-<br />
| 1028 || drafts_fullname || String || Path to default drafts folder. Preferred over "drafts"<br />
|-<br />
| 1029 || spam_fullname || String || Path to default spam folder. Preferred over "spam"<br />
|-<br />
| 1030 || confirmed_spam_fullname || String || Path to default confirmed-spam folder. Preferred over "confirmed_spam"<br />
|-<br />
| 1031 || confirmed_ham_fullname || String || Path to default confirmed-ham folder. Preferred over "confirmed_ham"<br />
|-<br />
| 1032 || pop3_refresh_rate || Number || The interval in minutes the POP3 account is refreshed<br />
|-<br />
| 1033 || pop3_expunge_on_quit || Boolean || Whether POP3 messages shall be deleted on actual POP3 account after retrieval or not<br />
|-<br />
| 1034 || pop3_delete_write_through || Boolean || If option "pop3_expunge_on_quit" is disabled, this property defines whether a delete in local INBOX also deletes affected message in actual POP3 account<br />
|-<br />
| 1035 || pop3_storage || String || The name of POP3 storage provider, default is "mailaccount"<br />
|-<br />
| 1036 || pop3_path || String || Path to POP3's virtual root folder in storage, default is name of the POP3 account beside default folders<br />
|-<br />
| 1037 || personal || String || The customizable personal part of email address<br />
|-<br />
| 1038 || reply_to || String || The customizable reply-to email address<br />
|-<br />
| 1039 || addresses || String || The comma-separated list of available E-Mail addresses including aliases. !! Only available for primary mail account !!<br />
|-<br />
| 1040 || meta || JSON data || Stores arbitrary JSON data as specified by client associated with the mail account<br />
|-<br />
| 1041 || archive || String || The name of the archive folder. Currently not functional!<br />
|-<br />
| 1042 || archive_fullname || String || The full name of the archive folder. Currently not functional!<br />
|-<br />
| 1043 || transport_auth || String || '''Available since v7.6.1''' Specifies the source for mail transport (SMTP) credentials. Possible values: "mail", "custom", and "none".<br>- "mail" signals to use the same credentials as given in associated mail store (IMAP, POP3).<br>- "custom" signals that individual credentials are supposed to be used (fields "transport_login" and "transport_password" are considered).<br>- "none" means the mail transport does not support any authentication mechanism (rare case!)<br />
|}<br />
<br />
=== Create a new mail account ===<br />
<br />
PUT <code>/ajax/account?action=new</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request: A JSON object describing the new account to create. See [[#MailAccountData | mail account data]].<br />
<br />
Response: A JSON object representing the inserted mail account. See [[#MailAccountData | mail account data]].<br />
<br />
=== Update a mail account ===<br />
<br />
PUT <code>/ajax/account?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request: A JSON object identifiying (field ID is present) and describing the account to update. See [[#MailAccountData | mail account data]].<br />
<br />
Response: A JSON object representing the updated mail account. See [[#MailAccountData | mail account data]].<br />
<br />
=== Delete a mail account ===<br />
<br />
PUT <code>/ajax/account?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: An array with the ID of the mail account to delete.<br />
<br />
=== Validate a mail account (which shall be created) ===<br />
<br />
PUT <code>/ajax/account?action=validate</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>tree</code> - An optional boolean parameter which indicates whether on successful validation the folder tree shall be returned (NULL on failure) or if set to "false" or missing only a boolean is returned which indicates validation result<br />
<br />
Request: A JSON object describing the new account to validate. See [[#MailAccountData | mail account data]].<br />
<br />
Response: Dependent on optional "tree" parameter a JSON folder object or a boolean value indicating the validation result<br />
<br />
The JSON folder object corresponding to [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]].<br />
Additionally a field "subfolder_array" is added which contains possible subfolders. This field is missing if a folder contains no subfolders.<br />
<br />
[[Category: OX6]]<br />
<br />
== Module Auto Configuration (since 6.22) ==<br />
<br />
=== Get Auto Configuration ===<br />
<br />
GET <code>/ajax/autoconfig?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>email</code> – Email Adress for which a mail configuration will be discovered.<br />
* <code>password</code> – Corresponding password for the mail account (optional)<br />
<br />
Response: A JSON Object containing the best available settings for an appropriate mail Server for the given email address. The fields are described in [[#MailAccountData | mail account data]]. The Data may be incomplete or even empty.<br />
<br />
== Module "user" (available with v6.14) ==<br />
<br />
The user module is used to access user information.<br />
<br />
=== Get all users ===<br />
<br />
GET <code>/ajax/user?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for users are defined in [[#CommonObjectData | Common object data]], [[#DetailedContactData | Detailed contact data]] and [[#DetailedUserData | Detailed user data]].<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Response with timestamp: An array with user data. Each array element describes one user and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
{| id="DetailedUserData" cellspacing="0" border="1"<br />
|+ align="bottom" | Detailed user data<br />
! ID !! Displayed name !! Name !! Type !! Value<br />
|-<br />
| 610 || Aliases || aliases || Array || The user's aliases<br />
|-<br />
| 611 || Time zone || timezone || String || The time zone ID.<br />
|-<br />
| 612 || Locale || locale || String || The name of user's entire locale, with the language, country and variant separated by underbars. E.g. "en", "de_DE"<br />
|-<br />
| 613 || Groups || groups || Array || The IDs of user's groups<br />
|-<br />
| 614 || Contact ID || contact_id || Number || The contact ID of the user<br />
|-<br />
| 615 || Login info || login_info || String || The user's login information<br />
|}<br />
<br />
=== Get a list of users ===<br />
<br />
PUT <code>/ajax/user?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – A comma-separated list of columns to return. Each column is specified by a numeric column identifier. Column identifiers for users are defined in [[#CommonObjectData | Common object data]], [[#DetailedContactData | Detailed contact data]] and [[#DetailedUserData | Detailed user data]].<br />
<br />
Request body: An array of numbers. Each number is the ID of requested user. Since v6.18.1, a <code>null</code> value in the array is interpreted as the currently logged in user.<br />
<br />
Response with timestamp: An array with user data. Each array element describes one user and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get a user ===<br />
<br />
GET <code>/ajax/user?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the requested user. Since v6.18.1, this parameter is optional: the default is the currently logged in user.<br />
<br />
Response with timestamp: An object containing all data of the requested user. The fields of the object are listed in [[#CommonObjectData | Common object data]], [[#DetailedContactData | Detailed contact data]] and [[#DetailedUserData | Detailed user data]].<br />
<br />
=== Update a user ===<br />
<br />
PUT <code>/ajax/user?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – Object ID of the updated user.<br />
* <code>timestamp</code> – Timestamp of the updated user. If the user was modified after the specified timestamp, then the update must fail.<br />
<br />
Request body: User object as described in [[#CommonObjectData | Common object data]], [[#DetailedContactData | Detailed contact data]] and [[#DetailedUserData | Detailed user data]]. Only modified fields are present.<br />
<br />
'''Note''': "timezone" and "locale" are the only fields from [[#DetailedUserData | Detailed user data]] which are allowed to be updated.<br />
<br />
Response with timestamp: An empty object.<br />
<br />
=== Search users ===<br />
<br />
PUT <code>/ajax/user?action=search</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>columns</code> – The requested fields<br />
* <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified. In case of use of column 609 (use count depending order for collected users with global address book) the parameter "order" ist NOT necessary and will be ignored.<br />
* <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.<br />
<br />
Request body: An Object as described in [[#SearchUsers | Search users]].<br />
<br />
{| id="SearchUsers" cellspacing="0" border="1"<br />
|+ align="bottom" | Search users<br />
! Name !! Type !! Value<br />
|-<br />
| pattern || String || Search pattern to find users. In the pattern, the character "*" matches zero or more characters and the character "?" matches exactly one character. All other characters match only themselves.<br />
|-<br />
| startletter || String || Search users with the given startletter. If this field is present, the pattern is matched against the user field which is specified by the property contact_first_letter_field on the server (default: last name). Otherwise, the pattern is matched against the display name.<br />
|}<br />
<br />
Alternative request body: An Object as described in [[#SearchUsersAlternative | Search users alternative]].<br />
<br />
{| id="SearchUsersAlternative" cellspacing="0" border="1"<br />
|+ align="bottom" | Search users alternative<br />
! Name !! Type !! Value<br />
|-<br />
| last_name || String || Searches users where the last name match with the given last name.<br />
|-<br />
| first_name || String || Searches users where the first name match with the given first name.<br />
|-<br />
| display_name || String || Searches users where the display name match with the given display name.<br />
|-<br />
| orSearch || Boolean || If set to true, the fields are connected through an OR search habit.<br />
|-<br />
| emailAutoComplete || Boolean || If set to true, results are guaranteed to contain at least one email adress and the search is performed by connecting the relevant fields through an OR search habit.<br />
|}<br />
<br />
Response: An array with user data. Each array element describes one user and is itself an array. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter.<br />
<br />
=== Get user attribute (available with v6.20) ===<br />
<br />
GET <code>/ajax/user?action=getAttribute</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – ID of the user. <br />
* <code>name</code> – The attribute name. <br />
<br />
Response without timestamp: A JSON object providing name and value of the requested attribute<br />
<pre><br />
{ "name":"somename", "value":"somevalue"}<br />
</pre><br />
<br />
=== Set user attribute (available with v6.20) ===<br />
<br />
PUT <code>/ajax/user?action=setAttribute</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – ID of the user. <br />
* <code>setIfAbsent</code> - Set to "true" to put the value only if the specified name is not already associated with a value, otherwise "false" to put value in any case<br />
<br />
Request body: A JSON object providing name and value of the attribute. If the <code>"value"</code> field id missing or NULL, the attribute is removed.<br />
<pre><br />
{ "name":"somename", "value":"somevalue"}<br />
</pre><br />
<br />
Response: The boolean value "true" if PUT was successful; otherwise "false"<br />
<br />
== Module "OAuth" (available with v6.20) ==<br />
<br />
The OAuth module is used to manage multiple OAuth accounts for certian online services for a user. The OAuth mechanism allows the Open-Xchange application to act as behalf of this user using previously obtained access tokens granted by user.<br />
<br />
The OAuth interface is divided into two parts: Account access and service's meta data access.<br />
<br />
=== OAuth account access ===<br />
<br />
The OAuth service account access description.<br />
<br />
<br />
==== Get all OAuth accounts ====<br />
<br />
GET <code>/ajax/oauth/accounts?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>serviceId</code> – The <b>optional</b> service meta data identifier. If missing all accounts of all services are returned; otherwise all accounts of specified service are returned<br />
<br />
Response: An array with account data. Each array element is a JSON object describing an OAuth account as specified in [[#OAuthAccountData | OAuth account data]].<br />
<br />
==== Get an OAuth account ====<br />
<br />
GET <code>/ajax/oauth/accounts?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The account identifier.<br />
<br />
Response: A JSON object describing an OAuth account as specified in [[#OAuthAccountData | OAuth account data]].<br />
<br />
{| id="OAuthAccountData" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth account<br />
! Field !! Type !! Description<br />
|-<br />
| id || Number || The numeric identifier of the OAuth account.<br />
|-<br />
| displayName || String || The account display name<br />
|-<br />
| serviceId || String || The identifier of the associated service meta data; e.g. <code>"com.openexchange.oauth.twitter"</code><br />
|-<br />
| token || String || The token<br />
|-<br />
| secret || String || The token secret<br />
|-<br />
|}<br />
<br />
==== Delete an OAuth account ====<br />
<br />
PUT <code>/ajax/oauth/accounts?action=delete</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The account identifier.<br />
<br />
Response: The boolean value "true" if successful<br />
<br />
==== Update an OAuth account ====<br />
<br />
PUT <code>/ajax/oauth/accounts?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The account identifier. May also be provided in request body's JSON OAuth account representation by <code>"id"</code> field.<br />
<br />
Request body: A JSON object providing the OAuth account fields to update. See [[#OauthAccountData | OAuth account data]]. Currently the only values which make sende being updated are <code>"displayName"</code> and the <code>"token"</code>-<code>"secret"</code>-pair.<br />
<br />
Response: The boolean value "true" if successful<br />
<br />
==== Initialize creation of an OAuth account ====<br />
<br />
GET <code>/ajax/oauth/accounts?action=init</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>serviceId</code> – The service meta data identifier; e.g. <code>"com.openexchange.oauth.twitter"</code><br />
<br />
Response: An JSON representation of the resulting interaction providing needed information to complete account creation. See [[#OauthInteractionData | OAuth interaction data]].<br />
<br />
{| id="OauthInteractionData" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth interaction<br />
! Field !! Type !! Description<br />
|-<br />
| authUrl || String || The numeric identifier of the OAuth account.<br />
|-<br />
| type || String || The interaction type name; <code>"outOfBand"</code> or <code>"callback"</code><br />
|-<br />
| token || String || The token<br />
|-<br />
| uuid || String || The UUID for this OAuth interaction<br />
|-<br />
|}<br />
<br />
==== Create an OAuth account ====<br />
<br />
Note: This action is typically called by provided call-back URL and is ony intended for manual invocation if "outOfBand" interaction is returned by preceeding <code>/ajax/oauth/account?action=init</code> step.<br />
<br />
PUT <code>/ajax/oauth/accounts?action=create</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module<br />
* <code>oauth_token</code> – The request token from preceeding OAuth interaction<br />
* <code>uuid</code> – The UUID of the preceeding OAuth interaction<br />
* <code>oauth_verfifier</code> – The verifier string which confirms that user granted access<br />
* <code>displayName</code> – The display name for the new account<br />
<br />
Response: A JSON object describing the newly created OAuth account as specified in [[#OAuthAccountData | OAuth account data]].<br />
<br />
=== OAuth service meta data access ===<br />
<br />
The OAuth service meta data access description.<br />
<br />
<br />
==== Get all OAuth services' meta data ====<br />
<br />
GET <code>/ajax/oauth/services?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: An array with service data. Each array element is a JSON object describing an OAuth service's meta data as specified in [[#OAuthServiceMetaData | OAuth service meta data]].<br />
<br />
==== Get an OAuth service's meta data ====<br />
<br />
GET <code>/ajax/oauth/services?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The service's identifier.<br />
<br />
Response: A JSON object describing an OAuth service's meta data as specified in [[#OAuthServiceMetaData | OAuth service meta data]].<br />
<br />
{| id="OAuthServiceMetaData" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth service meta data<br />
! Field !! Type !! Description<br />
|-<br />
| id || Number || The numeric identifier of the OAuth account.<br />
|-<br />
| displayName || String || The account display name<br />
|-<br />
|}<br />
<br />
== Module "JSlob" (available with v6.22) ==<br />
<br />
The JSlob module is used to store&retrieve arbitrary JSON-structured configuration for a single user.<br />
<br />
<br />
=== Get all JSLobs ===<br />
<br />
GET <code>/ajax/jslob?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>serviceId</code> – Optional identifier for the JSlob service. Default is <code>com.openexchange.jslob.config</code><br />
<br />
<br />
Response: An array with JSON configurations. Each array element is a JSON object representing a certain configuration consisting if a "id" and "jslob" field. See [[#JSlobData | JSlob data ]]<br />
<br />
{| id="JSlobData" cellspacing="0" border="1"<br />
|+ align="bottom" | JSlob data<br />
! Field !! Type !! Description<br />
|-<br />
| id || String or Number || The identifier of the JSlob.<br />
|-<br />
| jslob || JSON object || The JSON configuration.<br />
|-<br />
|}<br />
<br />
=== List denoted JSLobs ===<br />
<br />
PUT <code>/ajax/jslob?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>serviceId</code> – Optional identifier for the JSlob service. Default is <code>com.openexchange.jslob.config</code><br />
<br />
<br />
Request body: A JSON array of JSlob identifiers; e.g. <code>[ "1", "2", … ]</code><br />
<br />
Response: An array with JSON configurations. Each array element is a JSON object representing a certain configuration consisting if a "id" and "jslob" field. See [[#JSlobData | JSlob data ]]<br />
<br />
=== Delete a JSlob ===<br />
<br />
PUT <code>/ajax/jslob?action=set</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>serviceId</code> – Optional identifier for the JSlob service. Default is <code>com.openexchange.jslob.config</code><br />
* <code>id</code> – The JSlob identifier.<br />
<br />
<br />
Request body: An empty request body<br />
<br />
Response: Nothing<br />
<br />
=== Store a JSlob ===<br />
<br />
PUT <code>/ajax/jslob?action=set</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>serviceId</code> – Optional identifier for the JSlob service. Default is <code>com.openexchange.jslob.config</code><br />
* <code>id</code> – The identifier for the new JSlob to create<br />
<br />
<br />
Request body: A JSON object containing the "path" and "value" of the JSON configuration to store. If "path" is missing the current configuration<br />
is merged with given JSON object.<br />
<br />
Response: Nothing<br />
<br />
=== Update a single value inside a JSlob ===<br />
<br />
PUT <code>/ajax/jslob?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>serviceId</code> – Optional identifier for the JSlob service. Default is <code>com.openexchange.jslob.config</code><br />
* <code>id</code> – The identifier for the new JSlob to create<br />
<br />
<br />
Request body: The new value to store inside specified JSlob<br />
<br />
Response: A JSlob representation according to [[#JSlobData | JSlob data ]]<br />
<br />
=== REST-like access to JSlob module ===<br />
<br />
to be done...<br />
<br />
<br />
== Module "freebusy" (available with v6.22.1) ==<br />
<br />
Provides access to free/busy information.<br />
<br />
<br />
=== Get free/busy information ===<br />
<br />
GET <code>/ajax/freebusy?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>participant</code> – The participant to get the free/busy data for. May be either an internal user-, group- or resource-ID, or an e-mail address for external participants.<br />
* <code>from</code> – The lower (inclusive) limit of the requested time-range.<br />
* <code>until</code> – The upper (exclusive) limit of the requested time-range.<br />
* <code>merged</code> (optional) – True or False. Whether to pre-process the free/busy data on the server or not. This includes sorting as well as merging overlapping free/busy intervals.<br />
<br />
Response: An array of free/busy intervals as described in [[#FreeBusyInterval | Free/Busy interval]]<br />
<br />
{| id="FreeBusyInterval" cellspacing="0" border="1"<br />
|+ align="bottom" | Free/Busy interval<br />
! Name !! Type !! Value<br />
|-<br />
| start_date || Time || Start time of the interval.<br />
|-<br />
| end_date || Time || End time of the interval.<br />
|-<br />
| shown_as || Number || The busy status of this interval, one of:<br />
{| cellspacing="0" border="1"<br />
| 1 || unknown<br />
|-<br />
| 1 || reserved<br />
|-<br />
| 2 || temporary<br />
|-<br />
| 3 || absent<br />
|-<br />
| 4 || free<br />
|}<br />
|-<br />
| id || String || Object ID of the corresponding appointment if available.<br />
|-<br />
| folder_id || String || Folder ID of the corresponding appointment if available.<br />
|-<br />
| title || String || Title of the corresponding appointment if available.<br />
|-<br />
| location || String || Location of the corresponding appointment if available.<br />
|-<br />
| full_time || Boolean || True if the corresponding appointment is a whole day appointment, not present otherwise.<br />
|}<br />
<br />
<br />
=== Get a list of free/busy information ===<br />
<br />
PUT <code>/ajax/freebusy?action=list</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>from</code> – The lower (inclusive) limit of the requested time-range.<br />
* <code>until</code> – The upper (exclusive) limit of the requested time-range.<br />
* <code>merged</code> (optional) – True or False. Whether to pre-process the free/busy data on the server or not. This includes sorting as well as merging overlapping free/busy intervals.<br />
<br />
Request body: An array of participants to get the free/busy data for. Each participant may be either an internal user-, group- or resource-ID, or an e-mail address for external participants.<br />
<br />
Response: The free/busy data for all requested participants inside a JSON object with the participants as keys. Besides a combined data element for a requested group, all group members are resolved and listed seperately in the result. If the 'merged' view was requested, an additional data element named 'merged' representing a combined view for all requested participants is added to the results implicitly.<br />
<br />
<br />
== Messaging Services ==<br />
<br />
Messaging Services represent a messaging backend. The messaging services add a new folder module "messaging". <br />
<br />
A *Messaging Service* Object has the following structure:<br />
<br />
{| id="MessagingService" cellspacing="0" border="1"<br />
|+ align="bottom" | Messaging Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a messagingService. Usually a String in reverse domain name notation. Example: "com.openexchange.messaging.twitter"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Twitter" <br />
|-<br />
| formDescription || Array || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
| messagingActions || Array || An array of Strings a dynamic set of actions that are possible with messages of this service. Described in detail later on. <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
GET /ajax/messaging/service?action=all<br />
<br />
* session - A session ID previously obtained from the login module. <br />
<br />
Response: A standard response object containing an array of messaging service objects. <br />
<br />
<br />
GET /ajax/messaging/service?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the messaging service to load<br />
<br />
Response: A standard response object containing a messaging service object.<br />
<br />
== Messaging Accounts ==<br />
<br />
A messaging account represents the concrete configuration of an account of a given messaging service.<br />
A *messaging account* has the following structure:<br />
<br />
{| id="MessagingService" cellspacing="0" border="1"<br />
|+ align="bottom" | Messaging Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || Number || Identifies a given messaging account. This is not writeable and is generated by the server <br />
|-<br />
| messagingService || String || The messaging service id of the messaging service this account belongs to <br />
|-<br />
| displayName || String || User chosen String to identify a given account. Will also be translated into the folder name of the folder representing the accounts content <br />
|-<br />
| configuration || Object || Configuration data according to the formDescription of the relevant messagingService <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
PUT /ajax/messaging/account?action=new<br />
<br />
* session - A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON Object describing the account to be created.<br />
Response: A response object containing the new account id as its data.<br />
<br />
<br />
PUT /ajax/messaging/account?action=update<br />
<br />
* session - A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON Object describing the update to the account. Note that the "id" and "messagingService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
GET /ajax/messaging/account?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* messagingService - The messaging service id that the account belongs to<br />
* id - An account ID to load<br />
<br />
Response: A response object containing the JSON Object representing the loaded account as its data.<br />
<br />
GET /ajax/messaging/account?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* messagingService - The messaging service id that the account belongs to<br />
* id - An account ID to delete<br />
<br />
Response: A response object containing 1 as its data on success.<br />
<br />
GET /ajax/messaging/account?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* messagingService - (optional) list only those accounts that belong to the given messagingService.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
== Messaging Messages ==<br />
<br />
A Messaging Message represents a single message. It consists of some metadata, headers and a content. The content attribute varies by the content-type header. <br />
If the content type is text/* it is a string, if it is a multipart/* it is an array of objects, each representing a part of the multipart. If it is anything else<br />
it is considered binary and is a Base64 encoded string (ToDo : This is not smart enough yet. I suppose we'll have to include encoding options for binaries much like in our EAVJSONProposal).<br />
<br />
The folder id of a message follows a predefined format:<br />
<br />
<pre><br />
[messagingService]://[accountId]/[path]<br />
</pre><br />
<br />
for an imaginary example consider: "com.openexchange.messaging.twitter://535/defaultTimeline/directMessages"<br />
<br />
The structure of a Messaging Message is as follows:<br />
<br />
{| id="MessagingService" cellspacing="0" border="1"<br />
|+ align="bottom" | Messaging Message<br />
! Field !! Type !! Description<br />
|-<br />
|id ||String || The id of this message. Only unique in the given folder. <br />
|-<br />
|folder ||String || The folder id. <br />
|-<br />
|threadLevel ||Number || The nesting level of this message according to the conversation it's belonged to. May not be set. <br />
|-<br />
|flags ||Number || Bitmask showing the state of this message. The same as in the module "mail". <br />
|-<br />
|receivedDate ||Time || The time this message was received. <br />
|-<br />
|colorLabel ||Number || An arbitrary number marking this message in a certain color. The same as the colorLabel common to all groupware objects (see HTTP API)<br />
|-<br />
|user ||Array || An array of strings. Represents user flags. <br />
|-<br />
|size ||Number || The binary size of this message in bytes. <br />
|-<br />
|picture || String || A string depicting the URL to a picture for this message <br />
|-<br />
|url || String || A string that contains a link to the messages origin. Currently used in RSS messages.<br />
|-<br />
|headers ||JSONObject || A JSON Object of header data. Usually the value is either a String or an Array (if the headers has more than one value). Certain headers are rendered as more complex structures, see the section "Complex Headers". <br />
|-<br />
|content ||String or Array || See introductory note for Messaging Messages. <br />
|-<br />
|}<br />
<br />
The structure of a Multipart Part (an element of the content array in a multipart/* message) is a s follows:<br />
<br />
{| id="MessagingService" cellspacing="0" border="1"<br />
|+ align="bottom" | Multipart Element<br />
! Field !! Type !! Description<br />
|-<br />
|sectionId || String || The sectionId of this part.<br />
|-<br />
|headers || JSONObject || Same as above. <br />
|-<br />
|content || String or Array || Same as above. <br />
|-<br />
|}<br />
<br />
Some *Complex Headers* have a structure differing from simple key/value(s) pairs. These are:<br />
<br />
=== Content-Type ===<br />
<br />
The Content-Type header is represented as a JSON Object with the following structure:<br />
<br />
{| id="MessagingService" cellspacing="0" border="1"<br />
|+ align="bottom" | Content Type Header<br />
! Field !! Type !! Description<br />
|-<br />
| type || String || The type string (eg. text/plain). This governs the rendering of the content of a message. <br />
|-<br />
| params || Object || An Object with the keys "charset", containing the charset of this message and "name" pointing to the filename this part or message should have. <br />
|-<br />
|}<br />
<br />
When setting the content-type header in a messaging messages generated on the client the header may also be sent in it's short form. The short form is the type followed by a semi-colon separated list of key=value pairs<br />
of the params. For example: "text/plain;charset=utf-8;name=something.txt".<br />
<br />
=== Address Headers ===<br />
<br />
Address headers ( From, To,Cc,Bcc,Reply-To,Resent-Reply-To,Disposition-Notification-To,Resent-To,Sender,Resent-Sender,Resent-To,Resent-Cc,Resent-Bcc ) are formatted as an array of objects, or in case of "From" as a single object, with the attributes *address* and *personal*:<br />
<br />
{| id="MessagingService" cellspacing="0" border="1"<br />
|+ align="bottom" | Address Headers<br />
! Field !! Type !! Description<br />
|-<br />
| address || String || The technical part of the address<br />
|-<br />
| personal || String || A displayable description of the addressee. May be unset.<br />
|-<br />
|}<br />
<br />
When setting an address header the header may also be sent by clients in the short form <code>"personal &lt;address&gt;"</code>, for example <code>"Clark Kent &lt;clark.kent@dailyplanet.com&gt;"</code>. <br />
<br />
=== List renderings of Messaging Messages ===<br />
<br />
Actions returning lists of messages usually return only a selection of attributes of a message driven by a "columns" parameter. The columns that are addressable point either to attributes of the top-level message or its headers. <br />
<br />
{| id="MessagingService" cellspacing="0" border="1"<br />
|+ align="bottom" | Header Equivalence<br />
! Column !! Refers To<br />
|-<br />
| *column* | *refers to* <br />
|-<br />
| id || The id attribute <br />
|-<br />
| folderId || The folder attribute <br />
|-<br />
| contentType || The "Content-Type" header <br />
|-<br />
| from || The "From" header <br />
|-<br />
| to || The "To" header <br />
|-<br />
| cc || The "Cc" header <br />
|-<br />
| bcc || The "Bcc" header <br />
|-<br />
| subject || The "Subject" header <br />
|-<br />
| size || The size attribute <br />
|-<br />
| sentDate || The "Date" header <br />
|-<br />
| receivedDate || The receivedDate attribute <br />
|-<br />
| flags || The flags attribute <br />
|-<br />
| threadLevel || The threadLevel attribute <br />
|-<br />
| dispositionNotificationTo || The "Disposition-Notification-To" header. <br />
|-<br />
| priority || The "X-Priority" header <br />
|-<br />
| colorLabel || The colorLabel attribute <br />
|-<br />
| url || The url attribute <br />
|-<br />
| body || The content attribute <br />
|-<br />
| headers || The headers attribute <br />
|-<br />
|}<br />
<br />
=== JSON calls ===<br />
<br />
GET /ajax/messaging/message?action=get<br />
<br />
* session - A session ID previously obtained from the login module<br />
* id - The ID of the message to load<br />
* peek - (optional) if set to "true" the read/unread state of the message will not change. Defaults to false.<br />
* folder - The folder id<br />
<br />
Response: An Object representing the loaded message.<br />
<br />
PUT /ajax/messaging/message?action=send<br />
<br />
* session - A session ID previously obtained from the login module<br />
* recipients - (optional) If set the message is sent to the given list of recipients, otherwise this defaults to the "To" header of the message.<br />
<br />
Request Body: The Request Body should contain the JSON Object representing the message to be sent.<br />
Response: "1" as the data of a regular response on success.<br />
<br />
GET or PUT /ajax/messaging/message?action=perform<br />
<br />
* session - A session ID previously obtained from the login module<br />
* action - The messaging action to invoke<br />
* id - The id of the message the action should be invoked on. Only used on actions of type "storage".<br />
* folder - The folder id.<br />
<br />
Request Body: On actions of type "message" the body should contain the JSON representation of the message the action should be applied to.<br />
Response: Either 1 if no further user interaction is needed or a messaging message that, after having the user modify it has to be supplied back to the follower action of this action.<br />
<br />
Thus, to invoke a messaging action of type "storage" the folder and id are needed. Messaging actions of type "message" need a folder and message in the body. <br />
Messaging actions of type "none" need a messaging message and account. <br />
<br />
==== List style requests ====<br />
<br />
GET /ajax/messaging/message?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* columns - A comma-separated list of column names.<br />
* sort - (optional) A column to sort by.<br />
* order - (optional) The order direction. "asc" for ascending or "desc" for descending. Defaults to "asc"<br />
* folder - The folder id.<br />
<br />
Response: An array of arrays with the sub arrays containing the values of the fields asked for by the the columns parameter.<br />
<br />
<br />
PUT /ajax/messaging/messages?action=list<br />
<br />
* session - A session ID previously obtained from the login module<br />
* columns - A comma-separated list of column names.<br />
<br />
Request Body: An array of arrays with the folder and id as elements each identifying a message. <br />
<br />
Response: An array of arrays with the sub arrays containing the values of the fields asked for by the columns parameter.<br />
<br />
== Snippet module (available with v7.0.0/v6.22.0) ==<br />
<br />
=== Gets a certain snippet by identifier ===<br />
<br />
GET /ajax/snippet?action=get<br />
<br />
* session - The session identifier<br />
* id - The snippet identifier<br />
<br />
Response:<br />
The snippet's JSON representation; e.g.<br />
<br />
{<br />
"id": "1",<br />
"type": "signature",<br />
"props": {"x-custom": "any value"},<br />
"module": "mail",<br />
"displayname": "My signature",<br />
"misc": {"foo": "bar"},<br />
"createdby": 17,<br />
"content": "-- \\nMy name and position here",<br />
"accountid": 0,<br />
"shared": false,<br />
"files":<br />
[<br />
{<br />
"mimetype": "image/png; name=pic.png",<br />
"filename": "pic.png",<br />
"id": "46f49f8a-40d5-4f29-8bc9-728f3420864c",<br />
"size": 6074<br />
}<br />
]<br />
}<br />
<br />
=== Gets all snippets associated with the current user and context ===<br />
<br />
GET /ajax/snippet?action=all<br />
<br />
* session - The session identifier<br />
* type - Optional CSV of types to filter by; e.g. "signature"<br />
<br />
Response:<br />
A JSON array of snippets' JSON representations<br />
<br />
<br />
<br />
=== Gets certain snippets by identifiers ===<br />
<br />
GET /ajax/snippet?action=list<br />
<br />
* session - The session identifier<br />
<br />
Request body:<br />
A JSON array of snippet identifiers<br />
<br />
Response:<br />
A JSON array of snippets' JSON representations<br />
<br />
<br />
<br />
=== Gets a certain snippet's attachment by identifier ===<br />
<br />
GET /ajax/snippet?action=getattachment<br />
<br />
* session - The session identifier<br />
* id - The snippet identifier<br />
* attachmentid - The attachment identifier<br />
<br />
Response:<br />
The attachment's raw data<br />
<br />
<br />
<br />
=== Creates a new snippet ===<br />
<br />
PUT /ajax/snippet?action=new<br />
<br />
* session - The session identifier<br />
<br />
Request body:<br />
A JSON representation of the snippet.<br />
Excluding its attachments (see attach/detach actions)<br />
<br />
Response:<br />
The created snippet's identifier<br />
<br />
<br />
<br />
=== Updates a certain snippet by identifier ===<br />
<br />
PUT /ajax/snippet?action=update<br />
<br />
* session - The session identifier<br />
* id - The snippet identifier<br />
<br />
Request body:<br />
A JSON representation of the snippet providing the fields that should be changed.<br />
Excluding its attachments (see attach/detach actions)<br />
<br />
Response:<br />
The updated snippet's JSON representation<br />
<br />
<br />
<br />
=== Deletes a certain snippet by identifier ===<br />
<br />
PUT /ajax/snippet?action=delete<br />
<br />
* session - The session identifier<br />
* id - The snippet identifier (otherwise provide one or more identifiers through request body's JSON array)<br />
<br />
Request body:<br />
A JSON array of identifiers denoting the snippets to delete<br />
<br />
Response:<br />
An empty/dummy result (don't care)<br />
<br />
<br />
<br />
=== Attaches one or more files to an existing snippet ===<br />
<br />
POST /ajax/snippet?action=attach<br />
<br />
* session - The session identifier<br />
* id - The snippet identifier<br />
<br />
Request body:<br />
Multipart form data providing the upload files to attach to the snippet.<br />
<br />
Response:<br />
The updated snippet's identifier<br />
<br />
<br />
<br />
=== Detaches open or more files from an existing snippet ===<br />
<br />
PUT /ajax/snippet?action=detach<br />
<br />
* session - The session identifier<br />
* id - The snippet identifier<br />
<br />
Request body:<br />
A JSON array providing the identifiers of the attachments to remove from snippet<br />
<br />
Response:<br />
The updated snippet's identifier<br />
<br />
== Picture Halo (since 7.4.1) ==<br />
<br />
GET /appsuite/api/halo/contact/picture<br />
* session - (optional) falls back to the public session cookie<br />
* internal_userid - (optional) The internal user id of a user whose picture you want to load<br />
* userid - (optional) an alias for internal_userid<br />
* user_id - (optional) an alias for internal_userid<br />
* id - (optional) a contact id<br />
* email - (optional) an email to search for. Will pick global address book matches before regular matches. After that picks the most recently changed contact<br />
* email1 - (optional) an alias for email<br />
* email2 - (optional) another email address to use to find matches<br />
* email3 - (optional) and yet another email address to use to find matches<br />
<br />
''At least one of the optional search parameters should be set. All parameters are connected by OR during the search. More specific parameters like user_id or id are prioritized in case of multiple matches.''<br />
<br />
Response:<br />
The picture with proper eTag and caching headers set, or an HTTP Status 404 response, if no picture could be found.<br />
<br />
<br />
== Module "capabilities" (available with v7.4.2) ==<br />
<br />
Provides access to capabilities, i.e. modules or features that are available on the backend and the user has access to.<br />
<br />
=== Get a capability ===<br />
<br />
GET <code>/ajax/capabilities?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>id</code> – The identifier of the capability<br />
<br />
Response: The requested capability as described in [[#Capability| Capability]], if available, otherwise an empty result<br />
<br />
{| id="Capability" cellspacing="0" border="1"<br />
|+ align="bottom" | Capability<br />
! Name !! Type !! Value<br />
|-<br />
| id || String || The identifier of the capability<br />
|-<br />
| attributes || Object || A JSON object holding optional properties of the capability <br />
|}<br />
<br />
=== Get all capabilities ===<br />
<br />
GET <code>/ajax/capabilities?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: An array of capability objects as described in [[#Capability| Capability]].<br />
<br />
<br />
== Module "jump" (available with v7.6.0) ==<br />
<br />
The jump module is used to pass an acquired identity token for an authenticated user from one system to another for a single sign-on.<br />
<br />
=== Acquire an identity token ===<br />
<br />
GET <code>/ajax/jump?action=identityToken</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>system</code> – The identifier for the external service/system<br />
<br />
Response: The acquired identity token wrapped by a simple JSON object as described in [[#Jump| Jump]]<br />
<br />
{| id="Jump" cellspacing="0" border="1"<br />
|+ align="bottom" | Jump<br />
! Name !! Type !! Value<br />
|-<br />
| token || String || The identifier of the token<br />
|}<br />
<br />
== Module "find" (preliminary, available with v7.6.1) ==<br />
The Find API consists of calls for performing searches within the modules mail, contacts, calendar, tasks and drive. It was designed to provide an iterative approach where the search criteria can be refined step-wise until the desired items are found. The starting point is always an "autocomplete" request, that suggests possible search filters based on a users input. Those filters are grouped into categories, called "facets". A facet may provide one or more "values" with every value being a possible filter. A client is meant to remember every value that was selected by a user and include it within the following "autocomplete" and "query" requests, while "query" performs the actual search and returns the found items.<br />
<br />
Every request is bound to a module that must be specified via the URL-Parameter "module". Possible modules are<br />
* mail<br />
* contacts<br />
* calendar<br />
* tasks<br />
* drive<br />
<br />
=== Calls ===<br />
The find API provides two dedicated calls under the servlet path <code>find</code>:<br />
* action=autocomplete<br />
* action=query<br />
<br />
=== Facets ===<br />
The style of a facet is responsible for how the according object is structured, how it is handled on the server-side and how the client has to handle it.<br />
We distinguish three styles of facets:<br />
* simple<br />
* default<br />
* exclusive<br />
<br />
Every facet value contains an embedded "filter" object. The filter must not be changed by the client, it has to be seen as a black-box. Instead the filters<br />
of selected facet values have to be copied and sent to the server with the subsequent requests.<br />
<br />
==== Simple Facets ====<br />
A simple facet is a special facet that has exactly one value. The facets<br />
type and its value are strictly coupled, in a way that a display name for both,<br />
facet and value would be redundant. A simple facet generally denotes a logical field like<br />
'phone number'. Internally this logical field can map to several internal fields<br />
(e.g. 'phone_private', 'phone_mobile', 'phone_business'). In clients the facet as<br />
a whole can be displayed as a single item. Example: "Search for 'term' in field 'phone<br />
number'".<br />
<br />
<br />
{| id="Facet Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Facet Structure<br />
! Field !! Type !! Description<br />
|-<br />
| style || "simple" || Denotes that this is a facet of style simple<br />
|-<br />
| id || <string> || The id of this facet. Unique within an autocomplete response. Can be used to distinguish and filter certain facets.<br />
|-<br />
| name || <string> || A displayable (and localized) name for this facet. If absent, an "item" attribute is present.<br />
|-<br />
| item (optional) || <object> || A more complex object to display this facet. Attributes are "name", "detail" (optional) and "image_url" (optional).<br />
|-<br />
| filter || <object> || The filter to refine the search.<br />
|-<br />
| flags || <array> || An array of flags, represented as strings.<br />
|}<br />
<br />
Example:<br />
<pre><br />
{<br />
"id":"global",<br />
"style":"simple",<br />
"name":"test",<br />
"filter":{},<br />
"flags":[]<br />
}<br />
</pre><br />
<br />
==== Default Facets ====<br />
A default facet contains multiple values and may be present<br />
multiple times in search requests to filter results by a combination of different<br />
values (e.g. "mails with 'foo' and 'bar' in subject").<br />
<br />
Facet values may be one- or two-dimensional. A one-dimensional value can be displayed as is and contains an according filter object.<br />
A two-dimensional value contains an array "options" with every option defining different semantics of how the value is used to filter the search results.<br />
<br />
{| id="Default Facet Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Facet Structure<br />
! Field !! Type !! Description<br />
|-<br />
| style || "default" || Denotes that this is a facet of style default<br />
|-<br />
| id || <string> || The id of this facet. Unique within an autocomplete response. Can be used to distinguish and filter certain facets.<br />
|-<br />
| name || <string> || A displayable (and localized) name for this facet. If absent, an "item" attribute is present.<br />
|-<br />
| item (optional) || <object> || A more complex object to display this facet. Attributes are "name", "detail" (optional) and "image_url" (optional).<br />
|-<br />
| values || <array> || An array of facet values.<br />
|-<br />
| flags || <array> || An array of flags, represented as strings.<br />
|}<br />
<br />
{| id="Default Facet Value Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Value Structure<br />
! Field !! Type !! Description<br />
|-<br />
| id || <string> || The values id. Unique within one facet.<br />
|-<br />
| name || <string> || A displayable (and localized) name for this value. May be superseded with an "item" attribute. Absent if the value contains options.<br />
|-<br />
| item (optional) || <object> || A more complex object to display this value. Attributes are "name", "detail" (optional) and "image_url" (optional). Absent if the value contains options.<br />
|-<br />
| filter || <object> || The filter to refine the search. Absent if the value contains options.<br />
|-<br />
| options (optional) || <array> || An array of options.<br />
|}<br />
<br />
{| id="Default Facet Option Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Option Structure<br />
! Field !! Type !! Description<br />
|-<br />
| id || <string> || The options id. Unique within a set of options.<br />
|-<br />
| name || <string> || The displayable (and localized) name for this option.<br />
|-<br />
| filter || <object> || The filter to refine the search.<br />
|-<br />
|}<br />
<br />
Example:<br />
<pre><br />
{<br />
"id":"contacts",<br />
"style":"default",<br />
"name":"People",<br />
"values":[<br />
{<br />
"id":"contact/424242669/525793",<br />
"item":{<br />
"name":"Test Usere2123",<br />
"detail":"testuse1212r@example.com"<br />
},<br />
"options":[<br />
{<br />
"id":"from",<br />
"name":"From",<br />
"filter":{}<br />
},<br />
{<br />
"id":"to",<br />
"name":"To",<br />
"filter":{}<br />
},<br />
{<br />
"id":"all",<br />
"name":"From/To",<br />
"filter":{}<br />
}<br />
]<br />
}<br />
],<br />
"flags":[]<br />
}<br />
</pre><br />
<br />
==== Exclusive Facets ====<br />
An exclusive facet is a facet where the contained values are<br />
mutually exclusive. That means that the facet must only be present once<br />
in an autocomplete or query request.<br />
<br />
Facet values may be one- or two-dimensional. A one-dimensional value can be displayed as is and contains an according filter object.<br />
A two-dimensional value contains an array "options" with every option defining different semantics of how the value is used to filter the search results. <br />
<br />
{| id="Exclusive Facet Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Facet Structure<br />
! Field !! Type !! Description<br />
|-<br />
| style || "exclusive" || Denotes that this is a facet of style exclusive<br />
|-<br />
| id || <string> || The id of this facet. Unique within an autocomplete response. Can be used to distinguish and filter certain facets.<br />
|-<br />
| name || <string> || A displayable (and localized) name for this facet. If absent, an "item" attribute is present.<br />
|-<br />
| item (optional) || <object> || A more complex object to display this facet. Attributes are "name", "detail" (optional) and "image_url" (optional).<br />
|-<br />
| options || <array> || An array of facet values.<br />
|-<br />
| flags || <array> || An array of flags, represented as strings.<br />
|}<br />
<br />
{| id="Exclusive Facet Value Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Value Structure<br />
! Field !! Type !! Description<br />
|-<br />
| id || <string> || The values id. Unique within one facet.<br />
|-<br />
| name || <string> || A displayable (and localized) name for this value. May be superseded with an "item" attribute. Absent if the value contains options.<br />
|-<br />
| item (optional) || <object> || A more complex object to display this value. Attributes are "name", "detail" (optional) and "image_url" (optional). Absent if the value contains options.<br />
|-<br />
| filter || <object> || The filter to refine the search. Absent if the value contains options.<br />
|-<br />
| options (optional) || <array> || An array of options.<br />
|}<br />
<br />
{| id="Exclusive Facet Option Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Option Structure<br />
! Field !! Type !! Description<br />
|-<br />
| id || <string> || The options id. Unique within a set of options.<br />
|-<br />
| name || <string> || The displayable (and localized) name for this option.<br />
|-<br />
| filter || <object> || The filter to refine the search.<br />
|-<br />
|}<br />
<br />
Example:<br />
<pre><br />
{<br />
"id":"time",<br />
"style":"exclusive",<br />
"name":"Time",<br />
"options":[<br />
{<br />
"id":"last_week",<br />
"name":"last week",<br />
"filter":{}<br />
},<br />
{<br />
"id":"last_month",<br />
"name":"last month",<br />
"filter":{}<br />
},<br />
{<br />
"id":"last_year",<br />
"name":"last year",<br />
"filter":{}<br />
}<br />
],<br />
"flags":[]<br />
}<br />
</pre><br />
<br />
<br />
==== Active Facets ====<br />
Every value that has been selected by a user must be remembered and provided with every subsequent request. The representation of a facet within a request body differs from the one within an autocomplete response. We call those "active facets". Their representation is independent from their style.<br />
<br />
{| id="Active Facet Structure" cellspacing="0" border="1"<br />
|+ align="bottom" | Active Facet Structure<br />
! Field !! Type !! Description<br />
|-<br />
| facet || <string> || The id of the according facet.<br />
|-<br />
| value || <string> || The id of the according value. Must always be copied from the value object, not from a possibly according option (in the two-dimensional case).<br />
|-<br />
| filter || <object> || The filter object, copied from the value or option.<br />
|}<br />
<br />
<br />
=== Configuration ===<br />
According to the users configuration, some restrictions may apply that have to be heeded by clients. Those restrictions can be retrieved via the "config" or the "jslob" modules. The following restrictions may apply:<br />
<br />
* A user might have limited access to modules and therefore the Find API may only serve requests for a subset of all possible modules. The configuration object may contain an object with key "modules". Its value is an array containing all module identifiers that the user is allowed to use.<br />
<br />
* Some facets can be mandatory, i.e. they must be pre-defined by the client and provided with every request. Whether a facet is mandatory or not is decided on a per-module basis. The configuration object may contain an object with key "mandatory". Every facet that may be mandatory is specified via its id in that object (e.g. mandatory.folder). The value of such a key is either an array containing all module identifiers, where the facet is mandatory or null, if it is not manadatory in any module.<br />
<br />
* Due to performance reasons the service provider can enforce a minimium number of characters that have to be provided before an autocomplete request may be issued. That property is called "minimumQueryLength" and its value is an integer that specifies the minimum number of characters. If a client does not heed this property, the server will respond with an error if the provided user input is too short.<br />
<br />
==== Config Example ====<br />
<pre><br />
GET http://localhost/appsuite/api/config/search?session={{session}}<br />
Response:<br />
{<br />
"data": {<br />
"mandatory": {<br />
"folder": [<br />
"mail"<br />
]<br />
},<br />
"modules": [<br />
"mail",<br />
"contacts",<br />
"calendar",<br />
"tasks",<br />
"drive"<br />
]<br />
}<br />
}<br />
<br />
GET http://localhost/appsuite/api/config/minimumSearchCharacters?session={{session}}<br />
Response:<br />
{<br />
"data": 0<br />
}<br />
</pre><br />
<br />
==== JSLob Example ====<br />
<pre><br />
GET http://localhost/appsuite/api/jslob?action=get&id=io.ox/core&session={{session}}<br />
Response:<br />
{<br />
"data": {<br />
"id": "io.ox/core",<br />
"tree": {<br />
"search": {<br />
"modules": [<br />
"mail",<br />
"contacts",<br />
"calendar",<br />
"tasks",<br />
"drive"<br />
],<br />
"mandatory": {<br />
"folder": [<br />
"mail"<br />
]<br />
},<br />
"minimumQueryLength": 0<br />
}<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
=== autocomplete ===<br />
Mandatory URL parameters:<br />
* action=autocomplete<br />
* module=<module-name><br />
* session=<session-id><br />
<br />
Optional URL parameters:<br />
* limit=<int> - The maximum number of values returned per facet<br />
<br />
Request body: A JSON object containing the users input (specified as "prefix"), already selected facets and possible options.<br />
<br />
<br />
==== Example ====<br />
<pre><br />
PUT http://localhost/appsuite/api/find?action=autocomplete&module=mail&limit=3&session={{session}}<br />
{<br />
"prefix":"test", <br />
"facets":[<br />
{<br />
"facet":"folder",<br />
"value":"default0/INBOX"<br />
}<br />
],<br />
"options":{<br />
"timezone":"UTC",<br />
"admin":false<br />
}<br />
}<br />
<br />
Response:<br />
{<br />
"data":{<br />
"facets":[<br />
{<br />
"id":"global",<br />
"style":"simple",<br />
"name":"test",<br />
"filter":{},<br />
"flags":[]<br />
}, <br />
{<br />
"id":"contacts",<br />
"style":"default",<br />
"name":"People",<br />
"values":[<br />
{<br />
"id":"contact/424242669/525793",<br />
"item":{<br />
"name":"Test Usere2123",<br />
"detail":"testuse1212r@example.com"<br />
},<br />
"options":[<br />
{<br />
"id":"from",<br />
"name":"From",<br />
"filter":{}<br />
},<br />
{<br />
"id":"to",<br />
"name":"To",<br />
"filter":{}<br />
},<br />
{<br />
"id":"all",<br />
"name":"From/To",<br />
"filter":{}<br />
}<br />
]<br />
}<br />
],<br />
"flags":[]<br />
},<br />
{<br />
"id":"time",<br />
"style":"exclusive",<br />
"name":"Time",<br />
"options":[<br />
{<br />
"id":"last_week",<br />
"name":"last week",<br />
"filter":{}<br />
},<br />
{<br />
"id":"last_month",<br />
"name":"last month",<br />
"filter":{}<br />
},<br />
{<br />
"id":"last_year",<br />
"name":"last year",<br />
"filter":{}<br />
}<br />
],<br />
"flags":[]<br />
}<br />
]<br />
}<br />
}<br />
</pre><br />
<br />
=== query ===<br />
Mandatory URL parameters:<br />
* action=query<br />
* module=<module-name><br />
* session=<session-id><br />
<br />
Optional URL parameters:<br />
* columns=<column-ids> - A comma-separated list of the module-specific columns that shall be contained in the response items.<br />
<br />
Request body: A JSON object containing the selected facets and possible options. For pagination the keys "start" and "size" can be set.<br />
<br />
==== Example ====<br />
<pre><br />
PUT http://localhost/appsuite/api/find?action=query&module=mail&columns=102,600,601,602,603,604,605,607,608,610,611,614,652&session={{session}}<br />
{<br />
"facets":[<br />
{<br />
"facet":"folder",<br />
"value":"default0/INBOX",<br />
"filter":null<br />
},<br />
{<br />
"facet":"subject",<br />
"value":1409579708116,<br />
"filter":{<br />
"fields":[<br />
"subject"<br />
],<br />
"queries":[<br />
"lorem"<br />
]<br />
}<br />
}<br />
],<br />
"options":{<br />
"timezone":"UTC",<br />
"admin":false<br />
},<br />
"start":0,<br />
"size":101<br />
}<br />
<br />
Response:<br />
{<br />
"data":{<br />
"num_found":-1,<br />
"start":0,<br />
"size":1,<br />
"results":[<br />
{<br />
"color_label":0,<br />
"id":"110458",<br />
"folder_id":"default0/INBOX",<br />
"attachment":false,<br />
"from":[<br />
[<br />
"John Doe",<br />
"john.doe@example.com"<br />
]<br />
],<br />
"to":[<br />
[<br />
"Jane Doe",<br />
"jane.doe@example.com"<br />
]<br />
],<br />
"cc":[<br />
<br />
],<br />
"subject":"Lorem Ipsum",<br />
"size":7501,<br />
"received_date":1408531387000,<br />
"flags":32,<br />
"priority":3,<br />
"account_name":"E-Mail",<br />
"account_id":0<br />
}<br />
]<br />
}<br />
}<br />
</pre><br />
<br />
=== Available Options ===<br />
Every request body may contain an "options" object to finetune some specific behavior. Currently possible options are:<br />
* timezone: <tz-name> - The timezone to use if any dates are returned.<br />
* admin: <boolean> - true to include the context admin if it matches any search criteria. If the context admin shall always be ignored (i.e. not returned), false has to be set.<br />
<br />
=== Possible Flags ===<br />
Every facet may carry one or more flags that describe further aspects of that facet. Currently possible flags are:<br />
* conflicts - Specified in the form of "conflicts:<other-id>". A facet carrying this flag must not be combined with a facet of type <other-id>.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:OXtender_for_Business_Mobility_Installation_Guide&diff=15558OX6:OXtender for Business Mobility Installation Guide2013-08-29T15:09:36Z<p>Thomas.siedentopf: /* Log4j */</p>
<hr />
<div>= Open-Xchange OXtender for Business Mobility =<br />
<br />
== Components ==<br />
<br />
With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.<br />
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.<br />
<br />
=== Component Overview ===<br />
USM, EAS and OX work together as components. This is a general outline about how these components interact.<br />
<br />
When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.<br />
<br />
=== Requirements ===<br />
<br />
Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''Open-Xchange Server 6.16 or later is required to operate this extension.''' The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]<br />
<br />
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.<br />
<br />
<br />
Now the Open-Xchange groupware and admin service needs to be restarted:<br />
/etc/init.d/open-xchange-groupware restart<br />
/etc/init.d/open-xchange-admin restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=6.22/OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=v6.22.x}}<br />
<br />
=== RedHat Enterprise Linux 5 ===<br />
'''Please note,''' the last available version for RHEL5 is 6.22.0<br />
<br />
$ vim /etc/yum.repos.d/oxmobility.repo<br />
<br />
[oxmobility]<br />
name=Open-Xchange<br />
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-meta-mobility<br />
<br />
<br />
<br />
Now the Open-Xchange service needs to be restarted:<br />
<br />
/etc/init.d/open-xchange restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
== Installation on OX App Suite ==<br />
The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Business_Mobility_Installation_Guide<br />
<br />
== Configuration ==<br />
<br />
=== Mail Push ===<br />
<br />
In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle]] instructions on how to set up real mail push with cyrus.<br />
<br />
=== Open-Xchange configuration ===<br />
The configuration for USM and the EAS protocol can be found in these two configuration files:<br />
/opt/open-xchange/etc/usm.properties<br />
/opt/open-xchange/etc/eas.properties<br />
<br />
<br />
Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.<br />
com.openexchange.usm.ox.url=http://localhost/ajax/<br />
<br />
in case webserver and Open-Xchange aren't running on the same machine:<br />
com.openexchange.usm.ox.url=http://$FQDN/ajax/<br />
(Where $FQDN is the fully qualified domain name of your frontend system)<br />
<br />
On clustered setups, adjust the file<br />
/opt/open-xchange/etc/noipcheck.cnf<br />
to include the range of IP addresses of the servers on which USM is running.<br />
<br />
<br />
Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.<br />
<br />
=== Enabling ActiveSync for user accounts ===<br />
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.<br />
<br />
Activating ActiveSync for specific users:<br />
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on<br />
<br />
Activating ActiveSync for a whole context:<br />
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on<br />
<br />
== Log files and issue tracking ==<br />
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.<br />
<br />
=== Open-Xchange Server logfile ===<br />
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.<br />
<br />
=== Commons Logging ===<br />
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/file-logging.properties<br />
[...]<br />
com.openexchange.usm.level=FINE<br />
<br />
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== Log4j ===<br />
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/log4j.xml<br />
[...]<br />
<category name="com.openexchange.usm"><br />
<level value="DEBUG"/><br />
<appender-ref ref="SERVER_LOG"/><br />
</category><br />
<br />
Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== EAS debug logfile ===<br />
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.<br />
<br />
vim /opt/open-xchange/etc/eas.properties<br />
[...]<br />
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log<br />
<br />
This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.<br />
<br />
=== Network traffic ===<br />
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).<br />
<br />
== Bug-Reporting == <br />
Please report bugs via the Open-Xchange Bugzilla:<br />
<br />
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]<br />
<br />
* Product: OXtender for Business Mobility<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:OXtender_for_Business_Mobility_Installation_Guide&diff=15557OX6:OXtender for Business Mobility Installation Guide2013-08-29T15:09:18Z<p>Thomas.siedentopf: /* Commons Logging */</p>
<hr />
<div>= Open-Xchange OXtender for Business Mobility =<br />
<br />
== Components ==<br />
<br />
With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.<br />
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.<br />
<br />
=== Component Overview ===<br />
USM, EAS and OX work together as components. This is a general outline about how these components interact.<br />
<br />
When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.<br />
<br />
=== Requirements ===<br />
<br />
Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''Open-Xchange Server 6.16 or later is required to operate this extension.''' The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]<br />
<br />
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.<br />
<br />
<br />
Now the Open-Xchange groupware and admin service needs to be restarted:<br />
/etc/init.d/open-xchange-groupware restart<br />
/etc/init.d/open-xchange-admin restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=6.22/OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=v6.22.x}}<br />
<br />
=== RedHat Enterprise Linux 5 ===<br />
'''Please note,''' the last available version for RHEL5 is 6.22.0<br />
<br />
$ vim /etc/yum.repos.d/oxmobility.repo<br />
<br />
[oxmobility]<br />
name=Open-Xchange<br />
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-meta-mobility<br />
<br />
<br />
<br />
Now the Open-Xchange service needs to be restarted:<br />
<br />
/etc/init.d/open-xchange restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
== Installation on OX App Suite ==<br />
The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Business_Mobility_Installation_Guide<br />
<br />
== Configuration ==<br />
<br />
=== Mail Push ===<br />
<br />
In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle]] instructions on how to set up real mail push with cyrus.<br />
<br />
=== Open-Xchange configuration ===<br />
The configuration for USM and the EAS protocol can be found in these two configuration files:<br />
/opt/open-xchange/etc/usm.properties<br />
/opt/open-xchange/etc/eas.properties<br />
<br />
<br />
Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.<br />
com.openexchange.usm.ox.url=http://localhost/ajax/<br />
<br />
in case webserver and Open-Xchange aren't running on the same machine:<br />
com.openexchange.usm.ox.url=http://$FQDN/ajax/<br />
(Where $FQDN is the fully qualified domain name of your frontend system)<br />
<br />
On clustered setups, adjust the file<br />
/opt/open-xchange/etc/noipcheck.cnf<br />
to include the range of IP addresses of the servers on which USM is running.<br />
<br />
<br />
Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.<br />
<br />
=== Enabling ActiveSync for user accounts ===<br />
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.<br />
<br />
Activating ActiveSync for specific users:<br />
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on<br />
<br />
Activating ActiveSync for a whole context:<br />
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on<br />
<br />
== Log files and issue tracking ==<br />
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.<br />
<br />
=== Open-Xchange Server logfile ===<br />
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.<br />
<br />
=== Commons Logging ===<br />
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/file-logging.properties<br />
[...]<br />
com.openexchange.usm.level=FINE<br />
<br />
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== Log4j ===<br />
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/log4j.xml<br />
[...]<br />
<category name="com.openexchange.usm"><br />
<level value="DEBUG"/><br />
<appender-ref ref="SERVER_LOG"/><br />
</category><br />
<br />
Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== EAS debug logfile ===<br />
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.<br />
<br />
vim /opt/open-xchange/etc/eas.properties<br />
[...]<br />
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log<br />
<br />
This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.<br />
<br />
=== Network traffic ===<br />
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).<br />
<br />
== Bug-Reporting == <br />
Please report bugs via the Open-Xchange Bugzilla:<br />
<br />
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]<br />
<br />
* Product: OXtender for Business Mobility<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:OXtender_for_Business_Mobility_Installation_Guide&diff=15556OX6:OXtender for Business Mobility Installation Guide2013-08-29T15:09:03Z<p>Thomas.siedentopf: /* Open-Xchange configuration */</p>
<hr />
<div>= Open-Xchange OXtender for Business Mobility =<br />
<br />
== Components ==<br />
<br />
With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.<br />
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.<br />
<br />
=== Component Overview ===<br />
USM, EAS and OX work together as components. This is a general outline about how these components interact.<br />
<br />
When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.<br />
<br />
=== Requirements ===<br />
<br />
Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''Open-Xchange Server 6.16 or later is required to operate this extension.''' The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]<br />
<br />
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.<br />
<br />
<br />
Now the Open-Xchange groupware and admin service needs to be restarted:<br />
/etc/init.d/open-xchange-groupware restart<br />
/etc/init.d/open-xchange-admin restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=6.22/OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=v6.22.x}}<br />
<br />
=== RedHat Enterprise Linux 5 ===<br />
'''Please note,''' the last available version for RHEL5 is 6.22.0<br />
<br />
$ vim /etc/yum.repos.d/oxmobility.repo<br />
<br />
[oxmobility]<br />
name=Open-Xchange<br />
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-meta-mobility<br />
<br />
<br />
<br />
Now the Open-Xchange service needs to be restarted:<br />
<br />
/etc/init.d/open-xchange restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
== Installation on OX App Suite ==<br />
The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Business_Mobility_Installation_Guide<br />
<br />
== Configuration ==<br />
<br />
=== Mail Push ===<br />
<br />
In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle]] instructions on how to set up real mail push with cyrus.<br />
<br />
=== Open-Xchange configuration ===<br />
The configuration for USM and the EAS protocol can be found in these two configuration files:<br />
/opt/open-xchange/etc/usm.properties<br />
/opt/open-xchange/etc/eas.properties<br />
<br />
<br />
Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.<br />
com.openexchange.usm.ox.url=http://localhost/ajax/<br />
<br />
in case webserver and Open-Xchange aren't running on the same machine:<br />
com.openexchange.usm.ox.url=http://$FQDN/ajax/<br />
(Where $FQDN is the fully qualified domain name of your frontend system)<br />
<br />
On clustered setups, adjust the file<br />
/opt/open-xchange/etc/noipcheck.cnf<br />
to include the range of IP addresses of the servers on which USM is running.<br />
<br />
<br />
Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.<br />
<br />
=== Enabling ActiveSync for user accounts ===<br />
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.<br />
<br />
Activating ActiveSync for specific users:<br />
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on<br />
<br />
Activating ActiveSync for a whole context:<br />
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on<br />
<br />
== Log files and issue tracking ==<br />
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.<br />
<br />
=== Open-Xchange Server logfile ===<br />
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.<br />
<br />
=== Commons Logging ===<br />
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/file-logging.properties<br />
[...]<br />
com.openexchange.usm.level=FINE<br />
<br />
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== Log4j ===<br />
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/log4j.xml<br />
[...]<br />
<category name="com.openexchange.usm"><br />
<level value="DEBUG"/><br />
<appender-ref ref="SERVER_LOG"/><br />
</category><br />
<br />
Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== EAS debug logfile ===<br />
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.<br />
<br />
vim /opt/open-xchange/etc/eas.properties<br />
[...]<br />
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log<br />
<br />
This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.<br />
<br />
=== Network traffic ===<br />
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).<br />
<br />
== Bug-Reporting == <br />
Please report bugs via the Open-Xchange Bugzilla:<br />
<br />
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]<br />
<br />
* Product: OXtender for Business Mobility<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:OXtender_for_Business_Mobility_Installation_Guide&diff=15555OX6:OXtender for Business Mobility Installation Guide2013-08-29T15:08:33Z<p>Thomas.siedentopf: /* EAS debug logfile */</p>
<hr />
<div>= Open-Xchange OXtender for Business Mobility =<br />
<br />
== Components ==<br />
<br />
With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.<br />
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.<br />
<br />
=== Component Overview ===<br />
USM, EAS and OX work together as components. This is a general outline about how these components interact.<br />
<br />
When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.<br />
<br />
=== Requirements ===<br />
<br />
Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''Open-Xchange Server 6.16 or later is required to operate this extension.''' The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]<br />
<br />
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.<br />
<br />
<br />
Now the Open-Xchange groupware and admin service needs to be restarted:<br />
/etc/init.d/open-xchange-groupware restart<br />
/etc/init.d/open-xchange-admin restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=6.22/OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=v6.22.x}}<br />
<br />
=== RedHat Enterprise Linux 5 ===<br />
'''Please note,''' the last available version for RHEL5 is 6.22.0<br />
<br />
$ vim /etc/yum.repos.d/oxmobility.repo<br />
<br />
[oxmobility]<br />
name=Open-Xchange<br />
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-meta-mobility<br />
<br />
<br />
<br />
Now the Open-Xchange service needs to be restarted:<br />
<br />
/etc/init.d/open-xchange restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
== Installation on OX App Suite ==<br />
The download and installation information for Open-Xchange App Suite product family (Open-Xchange Server Edition and Hosting Edition) is available at: http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Business_Mobility_Installation_Guide<br />
<br />
== Configuration ==<br />
<br />
=== Mail Push ===<br />
<br />
In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle]] instructions on how to set up real mail push with cyrus.<br />
<br />
=== Open-Xchange configuration ===<br />
The configuration for USM and the EAS protocol can be found in these two configuration files:<br />
/opt/open-xchange/etc/groupware/usm.properties<br />
/opt/open-xchange/etc/groupware/eas.properties<br />
<br />
<br />
Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.<br />
com.openexchange.usm.ox.url=http://localhost/ajax/<br />
<br />
in case webserver and Open-Xchange aren't running on the same machine:<br />
com.openexchange.usm.ox.url=http://$FQDN/ajax/<br />
(Where $FQDN is the fully qualified domain name of your frontend system)<br />
<br />
On clustered setups, adjust the file<br />
/opt/open-xchange/etc/groupware/noipcheck.cnf<br />
to include the range of IP addresses of the servers on which USM is running.<br />
<br />
<br />
Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.<br />
<br />
=== Enabling ActiveSync for user accounts ===<br />
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.<br />
<br />
Activating ActiveSync for specific users:<br />
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on<br />
<br />
Activating ActiveSync for a whole context:<br />
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on<br />
<br />
== Log files and issue tracking ==<br />
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.<br />
<br />
=== Open-Xchange Server logfile ===<br />
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.<br />
<br />
=== Commons Logging ===<br />
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/file-logging.properties<br />
[...]<br />
com.openexchange.usm.level=FINE<br />
<br />
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== Log4j ===<br />
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/log4j.xml<br />
[...]<br />
<category name="com.openexchange.usm"><br />
<level value="DEBUG"/><br />
<appender-ref ref="SERVER_LOG"/><br />
</category><br />
<br />
Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== EAS debug logfile ===<br />
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.<br />
<br />
vim /opt/open-xchange/etc/eas.properties<br />
[...]<br />
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log<br />
<br />
This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.<br />
<br />
=== Network traffic ===<br />
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).<br />
<br />
== Bug-Reporting == <br />
Please report bugs via the Open-Xchange Bugzilla:<br />
<br />
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]<br />
<br />
* Product: OXtender for Business Mobility<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:OXtender_for_Business_Mobility_Installation_Guide&diff=12480OX6:OXtender for Business Mobility Installation Guide2013-01-04T09:17:07Z<p>Thomas.siedentopf: /* Apache Configuration */</p>
<hr />
<div>= Open-Xchange OXtender for Business Mobility =<br />
<br />
== Components ==<br />
<br />
With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.<br />
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.<br />
<br />
=== Component Overview ===<br />
USM, EAS and OX work together as components. This is a general outline about how these components interact.<br />
<br />
When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.<br />
<br />
=== Requirements ===<br />
<br />
Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''Open-Xchange Server 6.16 or later is required to operate this extension.''' The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]<br />
<br />
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.<br />
<br />
<br />
Now the Open-Xchange groupware and admin service needs to be restarted:<br />
/etc/init.d/open-xchange-groupware restart<br />
/etc/init.d/open-xchange-admin restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=6.22/OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility|version=v6.22.x}}<br />
<br />
=== RedHat Enterprise Linux 5 ===<br />
'''Please note,''' the last available version for RHEL5 is 6.22.0<br />
<br />
$ vim /etc/yum.repos.d/oxmobility.repo<br />
<br />
[oxmobility]<br />
name=Open-Xchange<br />
baseurl=http://LDBACCOUNT:LDBPASSWD@software.open-xchange.com/OX6/6.22/6.22.0/OXtender/BusinessMobilityOXtender/RHEL5/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-meta-mobility<br />
<br />
<br />
<br />
Now the Open-Xchange service needs to be restarted:<br />
<br />
/etc/init.d/open-xchange restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
== Configuration ==<br />
<br />
=== Mail Push ===<br />
<br />
In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle]] instructions on how to set up real mail push with cyrus.<br />
<br />
=== Open-Xchange configuration ===<br />
The configuration for USM and the EAS protocol can be found in these two configuration files:<br />
/opt/open-xchange/etc/groupware/usm.properties<br />
/opt/open-xchange/etc/groupware/eas.properties<br />
<br />
Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.<br />
com.openexchange.usm.ox.url=http://localhost/ajax/<br />
<br />
in case webserver and Open-Xchange aren't running on the same machine:<br />
com.openexchange.usm.ox.url=http://$FQDN/ajax/<br />
(Where $FQDN is the fully qualified domain name of your frontend system)<br />
<br />
On clustered setups, adjust the file<br />
/opt/open-xchange/etc/groupware/noipcheck.cnf<br />
to include the range of IP addresses of the servers on which USM is running.<br />
<br />
<br />
Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.<br />
<br />
=== Enabling ActiveSync for user accounts ===<br />
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.<br />
<br />
Activating ActiveSync for specific users:<br />
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on<br />
<br />
Activating ActiveSync for a whole context:<br />
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on<br />
<br />
== Log files and issue tracking ==<br />
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.<br />
<br />
=== Open-Xchange Server logfile ===<br />
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.<br />
<br />
=== Commons Logging ===<br />
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/file-logging.properties<br />
[...]<br />
com.openexchange.usm.level=FINE<br />
<br />
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== Log4j ===<br />
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/log4j.xml<br />
[...]<br />
<category name="com.openexchange.usm"><br />
<level value="DEBUG"/><br />
<appender-ref ref="SERVER_LOG"/><br />
</category><br />
<br />
Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== EAS debug logfile ===<br />
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.<br />
<br />
vim /opt/open-xchange/etc/groupware/eas.properties<br />
[...]<br />
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log<br />
<br />
This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.<br />
<br />
=== Network traffic ===<br />
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).<br />
<br />
== Bug-Reporting == <br />
Please report bugs via the Open-Xchange Bugzilla:<br />
<br />
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]<br />
<br />
* Product: OXtender for Business Mobility<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OXSE4UCS_Installation_en&diff=12207OXSE4UCS Installation en2012-12-05T09:49:40Z<p>Thomas.siedentopf: added oxmobility and outlook component</p>
<hr />
<div>= Introduction= <br />
The Open-Xchange Server Edition for Univention Corporate Server (OXSE4UCS) includes the groupware Open-Xchange and the integration packages for Univention Corporate Server (UCS).<br />
<br />
Open-Xchange Server Edition for Univention Corporate Server (OXSE4UCS) is tailored to professional users looking for a tried-and-tested solution for the management of their entire IT infrastructure including groupware or companies which already employ UCS and wish to expand their infrastructure with innovative groupware functions.<br />
<br />
More detailed information on UCS can be found on the Univention GmbH website: [http://www.univention.de/dokumentation.html http://www.univention.de/dokumentation.html].<br />
<br />
= First Step: Installation Univention Corporate Server =<br />
As OXSE4UCS is an expansion pack for the Univention Corporate Server, one or more UCS server(s) must be installed firstly.<br />
There are several possible different installation scenarios. In principle, OXSE4UCS can be installed on all UCS domain controller server roles: DC master, DC backup or DC slave. Installation on the server roles member server or base system is not currently possible.<br />
<br />
To start, the Univention Corporate Server systems are installed as usual with UCS 3.0. <br />
<br />
'''Download the UCS Installation package / DVD Image here:''' [http://www.univention.de/download-und-support/free-for-personal-use-edition/ http://www.univention.de/download-und-support/free-for-personal-use-edition/]<br />
<br />
If several systems are in the UCS domain, a check must be performed that the join procedure has been run on all servers. This is usually done at the end of the installation procedure. Further information on the installation of UCS can be found in the UCS manual: [http://www.univention.de/dokumentation.html http://www.univention.de/dokumentation.html]<br />
<br />
= Second Step: Installation Open-Xchange Server Edition for UCS =<br />
<br />
The password-protected Open-Xchange repository must be integrated on all the systems where OXSE4UCS packages are to be installed. The following Univention Configuration Registry variables (UCR variables) can be used to do this:<br />
<br />
<pre><br />
$ export LDBUSER="myusername" LDBPASS="secret"<br />
$ ucr set repository/online/component/ox/server=software.open-xchange.com \<br />
repository/online/component/ox/prefix=OX6/OXSEforUCS \<br />
repository/online/component/ox/username="$LDBUSER" \<br />
repository/online/component/ox/password="$LDBPASS" \<br />
repository/online/component/ox/version=current \<br />
repository/online/component/ox=enabled \<br />
repository/online/component/oxseforucs/server=software.open-xchange.com \<br />
repository/online/component/oxseforucs/prefix=OX6/OXSEforUCS \<br />
repository/online/component/oxseforucs/username="$LDBUSER" \<br />
repository/online/component/oxseforucs/password="$LDBPASS" \<br />
repository/online/component/oxoutlook/username="$LDBUSER" \<br />
repository/online/component/oxoutlook/password="$LDBPASS" \<br />
repository/online/component/oxmobility/username="$LDBUSER" \<br />
repository/online/component/oxmobility/password="$LDBPASS" \<br />
repository/online/component/oxseforucs/version=current \<br />
repository/online/component/oxseforucs=enabled<br />
</pre><br />
<br />
The access data (''myusername'' and ''secret'') are created when the Open-Xchange licence is activated and must be adapted here accordingly.<br />
<br />
<br />
== Installation on a DC master ==<br />
When installing OXSE4UCS on a DC master, only the '''univention-ox-meta-singleserver''' package requires installing. This can be performed via the Univention Management Console or on the command line:<br />
<br />
<pre><br />
$ univention-install univention-ox-meta-singleserver<br />
$ univention-upgrade<br />
</pre><br />
<br />
The univention-ox-meta-singleserver package automatically installs packages for the filtering of spam and viruses at the same time. If this is not required, the univention-ox and univention-mail-cyrus-ox packages can be installed instead of the univention-ox-meta-singleserver package.<br />
<br />
<br />
==Installation on a dedicated DC slave==<br />
In this installation scenario, the DC slave system acts as a standalone Open-Xchange groupware server. To start, the univention-ox-directory-integration package must be installed on the DC master in order to initiate integration in the UCS management system.<br />
<br />
<pre><br />
$ univention-install univention-ox-directory-integration<br />
$ univention-upgrade<br />
</pre><br />
<br />
The univention-ox-meta-singleserver package is installed on the DC slave which is to be used as the groupware server. In addition, the join scripts must also be run following the installation: <br />
<br />
<pre><br />
$ univention-install univention-ox-meta-singleserver<br />
$ univention-upgrade<br />
$ univention-run-join-scripts<br />
</pre><br />
<br />
The univention-ox-meta-singleserver package automatically installs packages for the filtering of spam and viruses. If this is not required, the univention-ox and univention-mail-cyrus-ox packages can be specified instead of the univention-ox-meta-singleserver package.<br />
<br />
<br />
== Installation in a distributed environment ==<br />
When installing a distributed environment, integration in the UCS management system must be performed firstly by installing univention-ox-directory-integration on DC Master.<br />
<br />
<pre><br />
$ univention-install univention-ox-directory-integration<br />
$ univention-upgrade<br />
</pre><br />
<br />
The following services can then be distributed on the other UCS systems: <br />
* IMAP server and spam/virus filtering<br />
* MySQL server (''mysql-server'')<br />
* OX instance (''univention-ox'')<br />
<br />
<br />
===MySQL server===<br />
The MySQL server is installed by installing the mysql-server package. <br />
<br />
<pre><br />
$ univention-install mysql-server<br />
$ univention-upgrade<br />
</pre><br />
<br />
The configuration of the MySQL server should be set so that the MySQL service can be accessed via the external network interfaces. To do this, for example, the bind-address option can be set to 0.0.0.0 in the MySQL configuration file /etc/mysql/my.cnf.<br />
<br />
<pre><br />
bind-address 0.0.0.0 <br />
</pre><br />
<br />
After the change, the MySQL service needs to be restarted: <br />
<br />
<pre><br />
$ /etc/init.d/mysql restart<br />
</pre><br />
<br />
and the MySQL port has to be configured in the local firewall settings:<br />
<br />
<pre><br />
$ ucr set security/packetfilter/tcp/3306/all=ACCEPT<br />
$ /etc/init.d/univention-firewall restart<br />
</pre><br />
<br />
In addition, the OX instances must be authorized to access the database. The following gives an example, which must be adapted to the environment at hand. <br />
<br />
<pre><br />
$ mysql <br />
mysql> GRANT ALL PRIVILEGES ON *.* TO \ <br />
'openexchange'@'ox-instance1.example.com' \ <br />
IDENTIFIED BY 'secret'; <br />
mysql> GRANT ALL PRIVILEGES ON *.* TO \ <br />
'openexchange'@'ox-instance2.example.com' \ <br />
IDENTIFIED BY 'secret'; <br />
mysql> GRANT ... <br />
mysql> FLUSH PRIVILEGES; <br />
mysql> exit <br />
$<br />
</pre><br />
<br />
=== Active OX instance ===<br />
<br />
Before installing the active OX instance certain environment variables must be set to ensure that the join scripts run later receive the corresponding permissions. The following gives an example, which must be adapted to the environment at hand. The variable OXDB defines the MySQL server to be used by the OX instance. The corresponding password should be saved in the variable OXDBPW. The standard IMAP server must be specified in the variable OXIMAPSERVER. Hostnames need to be specified as fully qualified domain names (FQDN). It is not possible to use IP addresses.<br />
<br />
<pre><br />
$ export HISTIGNORE="export*"<br />
$ export OXDB=oxdbserver.ucs.local<br />
$ export OXDBPW="secret"<br />
$ export OXIMAPSERVER=oximapserver.ucs.local <br />
</pre><br />
<br />
The '''univention-ox''' package must be installed on the active OX instance. <br />
<br />
<pre><br />
$ univention-install univention-ox<br />
$ univention-upgrade<br />
</pre><br />
<br />
Then the join scripts need to run: <br />
<br />
<pre><br />
$ univention-run-join-scripts<br />
</pre><br />
<br />
The responsible Sieve and SMTP server has to be configured via UCR variables:<br />
<br />
<pre><br />
$ ucr set ox/cfg/groupware/mailfilter.properties/SIEVE_SERVER=$OXIMAPSERVER<br />
</pre><br />
<br />
Finally, the environment variable OXDBPW with the password can be unset using the following command:<br />
<br />
<pre><br />
$ unset OXDBPW<br />
</pre><br />
<br />
=== IMAP server ===<br />
The IMAP server is installed by installing the '''univention-mail-cyrus-ox''' package.<br />
<br />
<pre><br />
$ univention-install univention-mail-cyrus-ox<br />
</pre><br />
<br />
The spam and virus check via amavis, spamassassin and clamav will be installed and activated automatically.<br />
<br />
A check should then be performed to see whether all join scripts have been run successfully: <br />
<br />
<pre><br />
$ univention-upgrade<br />
$ univention-run-join-scripts<br />
</pre><br />
<br />
'''Please note:'''<br />
The Cyrus spool directory ''/var/spool/cyrus'' should not be placed on a NFS share. Otherwise data consistency problems might occur with the index files.<br />
<br />
<br />
=== Additional passive OX instances ===<br />
Firstly, the '''univention-ox''' package must also be installed on the additional passive OX instances. <br />
<br />
<pre><br />
$ univention-install univention-ox<br />
$ univention-upgrade<br />
</pre><br />
<br />
Then the settings can be copied from the active OX instance. This can be done, for example, using the following command:<br />
<br />
<pre><br />
$ rsync -essh -a root@ox-instance1.ucs.local:/opt/open-xchange/. /opt/open-xchange/<br />
</pre><br />
<br />
The FQDN of the current computer must be entered in the'' /opt/open-xchange/etc/groupware/usm.properties'' file:<br />
<br />
<pre><br />
com.openexchange.usm.ox.url=ox-instance2.ucs.local<br />
</pre><br />
<br />
The FQDN of the current computer must also be entered in the'' /opt/open-xchange/etc/authplugin.properties'' file:<br />
<br />
<pre><br />
LDAP_HOST=ox-instance2.ucs.local<br />
</pre><br />
<br />
Finally, the groupware must be restarted on the passive OX instance:<br />
<br />
<pre><br />
$ /etc/init.d/open-xchange-admin restart<br />
$ /etc/init.d/open-xchange-groupware restart<br />
</pre><br />
<br />
=Updating=<br />
To update a UCS 2.3-2 system with OXSE4UCS 6.16 to 6.18.1 with UCS 2.4 or a UCS 2.4-4 system with OXSE4UCS 6.20 to UCS 3.0, the following variables must be set before the update:<br />
<br />
<pre><br />
$ ucr set repository/online/component/ox/version=current \<br />
repository/online/component/oxseforucs/version=current<br />
</pre><br />
<br />
The system can then be updated as usual for UCS using the ''univention-updater net'' command or the UMC module Online Update.<br />
<br />
<br />
=Administration=<br />
<br />
== UMC module “Licence management” ==<br />
<br />
The license management module supports you in the configuration of an Open-Xchange account and the selection of a suitable Open-Xchange license key. It is necessary to specify an Open-Xchange account to be able to select a license key previously saved in the account and install the UCS license. In addition, the account is also required for the installation of version and security updates from the Open-Xchange online repository, as this requires authentication.<br />
<br />
In this account, the same combination of username and password is required which was also used for the license database http://ldb.open-xchange.com.<br />
<br />
On an unconfigured system, the license management module displays the first configuration step directly, as shown in the figure. In all other cases, an overview of the current configuration is displayed.<br />
<br />
The first step involves entering the username and password of the Open-Xchange account. After continuing to the second configuration step via the ''Next'' button, the entered account information is automatically verified. Should it prove necessary to reset the password for an account, the ''Reset password'' button can be used to reset the password for an account. The username must be entered in the dialogue which opens; the password must be entered twice. On confirmation, an e-mail is sent to the e-mail address specified for the account containing a confirmation link, which can be opened in the browser of your choice to complete the process.<br />
<br />
The second and final step requires to select a suitable Open-Xchange license key. A variety of information is stored in the license database for a license key (e.g., the primary mail domain or the number of licensed users). In addition, a UCS license is saved for every license key in the license database, which is downloaded from the LDB server and installed on the local system when this wizard is finished.<br />
<br />
If several keys are saved in the specified account, it is important to select the correct key, as it will otherwise not be possible to complete the configuration if the information saved in the license database does not correspond to the local system.<br />
<br />
When performing the configuration for the first time, you may be prompted to confirm the end user license agreement (EULA) for the selected product via the checkbox.<br />
<br />
After clicking on the ''Finish'' button, the UCS license is downloaded and installed. The Open-Xchange license key is then configured on the local system. This procedure can take a few seconds.<br />
<br />
Once the configuration is complete, the module redirects to the overview page. This page displays the currently configured Open-Xchange account, the status of the specified user data (valid/invalid), the license key selected for this system and the LDAP base of the installed system.<br />
<br />
Following successful configuration, it is possible to ''Switch to the Online Update module'' directly from here and install the available updates.<br />
<br />
If it proves necessary to change the Open-Xchange account or it has been relicensed, you can open the configuration wizard again using the ''Change settings'' button. For relicensing, it is necessary to perform the configuration procedure anew so that the modified license information is adopted on the local system.<br />
<br />
<br />
== User and group management ==<br />
<br />
New users and groups can be created using the Univention Management Console (UMC). The UMC can be accessed on the DC master via a web browser at https://<IP address of DC master>/umc/. It is possible to log in as the Administrator user using the password specified during the installation.<br />
<br />
When creating a user, the ''open-xchange groupware account'' user template should be selected. This preselects all Open-Xchange specific settings.<br />
<br />
== System messages ==<br />
The mail/alias/root UCS variable must be set so that system messages can be delivered. To do this, either a new account can be created or, alternatively, oxadmin@DOMAIN is provided for this purpose:<br />
<br />
<pre><br />
$ ucr set mail/alias/root=oxadmin@ucs.local<br />
$ newaliases<br />
$ /etc/init.d/postfix reload<br />
</pre><br />
<br />
It is possible to log in as the oxadmin user in the Open-Xchange web interface using the password from the ''/etc/ox-secrets/context10.secret'' file.<br />
<br />
<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Template:OXConfiguration&diff=12146Template:OXConfiguration2012-11-23T16:14:29Z<p>Thomas.siedentopf: /* Open-Xchange configuration */</p>
<hr />
<div>= Open-Xchange configuration =<br />
<br />
To avoid confusion right at the start notice that Open-Xchange uses multiple administration levels and requires different credentials at some stages at the installation and server management. Note that the passwords chosen at this guide are weak and should be replaced by stronger passwords.<br />
* The MySQL database user<br />
** Username: openexchange<br />
** Password used at this guide: db_password<br />
** Responsibility: Execute all kinds of database operations<br />
<br />
* The Open-Xchange Admin Master<br />
** Username: oxadminmaster<br />
** Password used at this guide: admin_master_password<br />
** Responsibility: Manage contexts, manage all kinds of low level server configuration<br />
<br />
* The Context Admin<br />
** Username: oxadmin<br />
** Password used at this guide: admin_password<br />
** Responsibility: Manage users/groups/resources inside a context<br />
<br />
In order to setup the Open-Xchange Server it is mandatory to have the database running:<br />
<br />
$ {{{mysqlstart}}}<br />
<br />
'''Note:''' in case of a distributed setup, it is recommended to start mysql with --skip-name-resolve or to add all hosts to the hosts file of the database server so that slow DNS responses do not slow down the creation of new database connections. <br><br />
In a distributed setup you should also take care of the fact that Open-Xchange supports only a Statement Based Replication at the moment ([http://dev.mysql.com/doc/refman/5.1/en/replication-formats.html http://dev.mysql.com/doc/refman/5.1/en/replication-formats.html]). See also [http://oxpedia.org/wiki/index.php?title=Load_balancing_and_clustering Load_balancing_and_clustering]<br />
<br />
a good idea is to add the Open-Xchange binaries to PATH:<br />
<br />
$ echo PATH=$PATH:/opt/open-xchange/sbin/ >> ~/.bashrc && . ~/.bashrc<br />
<br />
Now we have to initialize the Open-Xchange ''configdb'' database. This can all be done by executing the ''initconfigdb'' script.<br />
<br />
$ /opt/open-xchange/sbin/initconfigdb --configdb-pass=db_password -a<br />
<br />
Add the ''-i'' option if you want to remove an already existing open-xchange configdb.<br />
<br />
'''Note:''' The -a parameter adds an administrative account to mysql, this administrative account is required for the creation of the oxdatabase database, you may find problems following the instructions of this tutorial if you either set a mysql root password or do not create this administrative account, if you have manually setup this administrative account, grant the permissions for database creation or you may find a problem in the context creation.<br />
<br />
Before starting any service, all basic configuration files need to be set up correctly. The ''--configdb-pass'' option indicates the password of the ''openexchange'' database user previously created, the ''--master-pass'' options specifies the password of the Open-Xchange ''adminmaster'' user that will be created when executing the ''oxinstaller'' script.<br />
<br />
Now is a good time to configure the way OX will authenticate to your mail server. Edit the file /opt/open-xchange/etc/groupware/mail.properties and change the com.openexchange.mail.loginSource to use. This is very important for servers that require your full email address to log in with.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Template:OXConfiguration&diff=12145Template:OXConfiguration2012-11-23T16:11:50Z<p>Thomas.siedentopf: /* Open-Xchange configuration */</p>
<hr />
<div>= Open-Xchange configuration =<br />
<br />
To avoid confusion right at the start notice that Open-Xchange uses multiple administration levels and requires different credentials at some stages at the installation and server management. Note that the passwords chosen at this guide are weak and should be replaced by stronger passwords.<br />
* The MySQL database user<br />
** Username: openexchange<br />
** Password used at this guide: db_password<br />
** Responsibility: Execute all kinds of database operations<br />
<br />
* The Open-Xchange Admin Master<br />
** Username: oxadminmaster<br />
** Password used at this guide: admin_master_password<br />
** Responsibility: Manage contexts, manage all kinds of low level server configuration<br />
<br />
* The Context Admin<br />
** Username: oxadmin<br />
** Password used at this guide: admin_password<br />
** Responsibility: Manage users/groups/resources inside a context<br />
<br />
In order to setup the Open-Xchange Server it is mandatory to have the database running:<br />
<br />
$ {{{mysqlstart}}}<br />
<br />
'''Note:''' in case of a distributed setup, it is recommended to start mysql with --skip-name-resolve or to add all hosts to the hosts file of the database server so that slow DNS responses do not slow down the creation of new database connections. <br><br />
In a distributed setup you should also take care of the fact that Open-Xchange supports only a Statement Based Replication at the moment ([http://dev.mysql.com/doc/refman/5.1/en/replication-formats.html http://dev.mysql.com/doc/refman/5.1/en/replication-formats.html]). See also [http://oxpedia.org/wiki/index.php?title=Load_balancing_and_clustering Load_balancing_and_clustering]<br />
<br />
a good idea is to add the Open-Xchange binaries to PATH:<br />
<br />
$ echo PATH=$PATH:/opt/open-xchange/sbin/ >> ~/.bashrc && . ~/.bashrc<br />
<br />
Now we have to initialize the Open-Xchange ''configdb'' database. This can all be done by executing the ''initconfigdb'' script.<br />
<br />
$ /opt/open-xchange/sbin/initconfigdb --configdb-pass=db_password -a<br />
<br />
Add the ''-i'' option if you want to remove an already existing open-xchange configdb.<br />
<br />
'''Note:''' The -a parameter adds an administrative account to mysql, this administrative account is required for the creation of the oxdatabase database, you may find problems following the instructions of this tutorial if you either set a mysql root password or do not create this administrative account, if you have manually setup this administrative account, grant the permissions for database creation or you may find a problem in the context creation.<br />
<br />
Before starting any service, all basic configuration files need to be set up correctly. The ''--configdb-pass'' option indicates the password of the ''openexchange'' database user previously created, the ''--master-pass'' options specifies the password of the Open-Xchange ''adminmaster'' user that will be created when executing the ''oxinstaller'' script.<br />
<br />
Now is a good time to configure the way OX will authenticate to your mail server. Edit the file /opt/open-xchange/etc/mail.properties and change the com.openexchange.mail.loginSource to use. This is very important for servers that require your full email address to log in with.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=11753Caldav carddav Bundles2012-10-12T09:18:25Z<p>Thomas.siedentopf: /* Alternative 1: Apache vhost (recommended) */</p>
<hr />
<div>= Installation and Configuration of the CalDAV- and CardDAV-bundles =<br />
<br />
The Open-Xchange server can be accessed via it's CalDAV- and CardDAV-interfaces to allow the synchronization of Calendar- and Contact-data with external applications like the Mac OS X iCal and Address Book clients. The synchronization protocols are available and supported for all customers with a valid Open-Xchange license of Open-Xchange Server Edition and Open-Xchange Hosting Edition starting with Version 6.20.1 Rev5.<br />
<br />
CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. The CalDAV interface publishes all the user's calendar folders via CalDAV so the user can subscribe to them in a client application. Similarly, the CardDAV interface publishes the user's contact folders. Depending on the used client, the user can either subscribe one or more folders, or access all available data in an aggregated way. <br />
<br />
== User Guide and Client Configuration ==<br />
Please find further information regarding the client configuration at [[CalDAVClients]] and [[CardDAVClients]].<br />
<br />
== Webserver Configuration ==<br />
In order to redirect DAV requests to the appropiate servlets, the webserver's configuration may need to be adjusted using one of the following alternatives.<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
Please edit your file /etc/apache2/ox6.conf so that ''' the existing OX configuration as well as the CalDAV/CardDav configuration are placed inside their own virtual hosts sections.'''.<br />
<br />
This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
$ vi /etc/apache2/ox6.conf <br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.MYSERVER.TLD<br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
</Proxy><br />
ProxyPass / ajp://localhost:8009/servlet/dav/ smax=0 ttl=60 retry=5<br />
</VirtualHost><br />
<br />
<VirtualHost *:80><br />
ServerName MYSERVER.TLD<br />
ServerAdmin webmaster@localhost<br />
DocumentRoot /var/www/<br />
<br />
<Directory /var/www/><br />
AllowOverride None<br />
Order allow,deny<br />
allow from all<br />
RedirectMatch ^/$ /ox6/<br />
Options +FollowSymLinks +SymLinksIfOwnerMatch<br />
</Directory><br />
# deflate<br />
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript<br />
<br />
# pre-compressed files<br />
AddType text/javascript .jsz<br />
AddType text/css .cssz<br />
AddType text/xml .xmlz<br />
AddType text/plain .po<br />
<br />
AddEncoding gzip .jsz .cssz .xmlz<br />
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip<br />
<br />
ExpiresActive On<br />
<br />
<Location /ox6><br />
# Expires (via ExpiresByType to override global settings)<br />
ExpiresByType image/gif "access plus 6 months"<br />
ExpiresByType image/png "access plus 6 months"<br />
ExpiresByType image/jpg "access plus 6 months"<br />
ExpiresByType image/jpeg "access plus 6 months"<br />
ExpiresByType text/css "access plus 6 months"<br />
ExpiresByType text/html "access plus 6 months"<br />
ExpiresByType text/xml "access plus 6 months"<br />
ExpiresByType text/javascript "access plus 6 months"<br />
ExpiresByType text/x-js "access plus 6 months"<br />
ExpiresByType application/x-javascript "access plus 6 months"<br />
ExpiresDefault "access plus 6 months"<br />
Header append Cache-Control "private"<br />
Header unset Last-Modified<br />
Header unset Vary<br />
# Strip version<br />
RewriteEngine On<br />
RewriteRule v=\w+/(.+) $1 [L]<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
<br />
<Location /ox6/ox.html><br />
ExpiresByType text/html "now"<br />
ExpiresDefault "now"<br />
Header unset Last-Modified<br />
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
<br />
<Location /ox6/index.html><br />
ExpiresByType text/html "now"<br />
ExpiresDefault "now"<br />
Header unset Last-Modified<br />
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
</VirtualHost><br />
<br />
If you use this method, you have to make sure that dav.MYSERVER.TLD is reachable, your dns configuration need an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to /tmp.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.<br />
<br />
$ vi /etc/apache2/ox6.conf<br />
<br />
RewriteEngine On<br />
RewriteCond %{HTTP_USER_AGENT} Calendar [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DataAccess [OR]<br />
RewriteCond %{HTTP_USER_AGENT} DAVKit [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Lightning [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adresboek [OR]<br />
RewriteCond %{HTTP_USER_AGENT} dataaccessd [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Preferences [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Adressbuch [OR]<br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV<br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P]<br />
<br />
'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.<br />
<br />
<br />
== Which packages do I need? ==<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
* open-xchange-webdav-directory - Assembles the *DAV interfaces into a common tree. This is needed for publishing certain properties so clients accept the OX is a WebDAV Server.<br />
* open-xchange-webdav-acl - The WebDAV equivalent of the /ajax/user interface. Allows clients to discover the current and other users and their addressbooks and calendars.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
<br />
== Installation on Open-Xchange v6.22 == <br />
<br />
=== Debian GNU/Linux 6.0 === <br />
<br />
Add the following entry to /etc/apt/sources.list if not already present:<br />
<br />
deb http://software.open-xchange.com/OX6/6.22/6.22.0/backend/DebianSqueeze/all/<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory<br />
<br />
=== SUSE Linux Enterprise Server 11 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
$ zypper ar http://software.open-xchange.com/OX6/6.22/6.22.0/backend/SLES11 ox<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory<br />
<br />
=== RedHat Enterprise Linux 6 ===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=http://software.open-xchange.com/OX6/6.22/6.22.0/backend/RHEL6/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory<br />
<br />
=== RedHat Enterprise Linux 5 ===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=http://software.open-xchange.com/OX6/6.22/6.22.0/backend/RHEL5/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory<br />
<br />
=== CentOS 5 ===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=http://software.open-xchange.com/OX6/6.22/6.22.0/backend/RHEL5/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory<br />
<br />
=== CentOS 6 ===<br />
<br />
Start a console and create a software repository file if not already present:<br />
<br />
$ vim /etc/yum.repos.d/ox.repo<br />
<br />
[ox]<br />
name=Open-Xchange<br />
baseurl=http://software.open-xchange.com/OX6/6.22/6.22.0/backend/RHEL6/<br />
gpgkey=http://software.open-xchange.com/oxbuildkey.pub<br />
enabled=1<br />
gpgcheck=1<br />
metadata_expire=0m<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory<br />
<br />
== CalDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files caldav.properties and caldav.yml:<br />
<br />
===com.openexchange.caldav.enabled===<br />
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
This means: In general CalDAV is turned off, but using the contextSets feature of the config cascade it is turned on for everyone that has infostore access.<br />
<br />
===com.openexchange.caldav.tree===<br />
Configures the ID of the folder tree used by the CalDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.caldav.interval.start===<br />
Defines the minimum end time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_month" (default), "one_year" and "six_months". <br />
<br />
===com.openexchange.caldav.interval.end===<br />
Defines the maximum start time of appointments to be synchronized via the CalDAV interface, relative to the current date. Possible values are "one_year" (default) and "two_years". <br />
<br />
===com.openexchange.caldav.url===<br />
Tells users where to find a caldav folder. This can be displayed in frontends. You can use the variables [hostname] and [folderId]. If you chose to deploy caldav as a virtual host (say 'dav.open-xchange.com') use https://dav.open-xchange.com/caldav/[folderId] as the value. If you are using user-agent sniffing use https://[hostname]/caldav/[folderId].<br />
<br />
<br />
== CardDAV Configuration ==<br />
<br />
The following configuration options are available in the configuration files carddav.properties and carddav.yml:<br />
<br />
===com.openexchange.carddav.enabled===<br />
Similarly to CalDAV, the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:<br />
<br />
/opt/open-xchange/etc/groupware/carddav.properties:<br />
com.openexchange.carddav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/carddav.yml<br />
premium:<br />
com.openexchange.carddav.enabled: true<br />
withTags: ucInfostore<br />
<br />
===com.openexchange.carddav.ignoreFolders===<br />
A comma-separated list of folder IDs to exclude from the synchronization. Use this to disable syncing of very large folders (e.g. the global address list in large contexts, which always has ID 6). By default, no folders are excluded.<br />
<br />
===com.openexchange.carddav.tree===<br />
Configures the ID of the folder tree used by the CardDAV interface. Currently, this should be set to the default value of '0'.<br />
<br />
===com.openexchange.carddav.exposedCollections===<br />
Controls which collections are exposed via the CardDAV interface. Possible values are '0', '1' and '2'. A value of '1' makes each visible folder available as a resource collection, while '2' only exposes an aggregated collection containing all contact resources from all visible folders. The default value '0' exposes either an aggregated collection or individual collections for each folder, depending on the client's user-agent that is matched against the pattern in 'userAgentForAggregatedCollection'. <br />
<br />
===com.openexchange.carddav.userAgentForAggregatedCollection===<br />
Regular expression to match against the client's user-agent to decide whether the aggregated collection is exposed or not. The default pattern matches all known varieties of the Mac OS Addressbook client, that doesn't support multiple collections. Only used if 'exposedCollections' is set to '0'. The pattern is used case insensitive. <br />
<br />
===com.openexchange.carddav.reducedAggregatedCollection===<br />
Specifies if all visible folders are used to create the aggregated collection, or if a reduced set of folders only containing the global addressbook and the personal contacts folders should be used. This setting only influences the aggregated collection that is used for clients that don't support multiple collections. Possible values are 'true' and 'false.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:OXtender_for_Business_Mobility_Installation_Guide&diff=10991OX6:OXtender for Business Mobility Installation Guide2012-08-24T09:45:13Z<p>Thomas.siedentopf: removed broken link</p>
<hr />
<div>= Open-Xchange OXtender for Business Mobility =<br />
<br />
== Components ==<br />
<br />
With the OXtender for Business Mobility, Open-Xchange also introduces the Universal Synchronization Module (USM). This module provides a framework for synchronization protocols such as Microsoft Exchange ActiveSync (EAS) or other services building on this foundation. USM acts as a layer between the Open-Xchange HTTP API and the synchronization protocol. It handles synchronization specific tasks like conflict management.<br />
The synchronization stack (USM) and protocol implementation (EAS) are shipped as OSGi bundles and run as a plug-in of an Open-Xchange instance.<br />
<br />
=== Component Overview ===<br />
USM, EAS and OX work together as components. This is a general outline about how these components interact.<br />
<br />
When the device initiates a synchronization through ActiveSync, it contacts the webserver using the URL /Microsoft-Server-ActiveSync via HTTP/s. This URL is forwarded to the Open-Xchange application server where the corresponding servlet is offered by the EAS component. The EAS component then uses USM to initiate a connection to the OX HTTP API and exchanges groupware data. In all cases, USM works as an client to the Open-Xchange HTTP API. It also uses some database tables which are accessed through the Open-Xchange SQL interface to store metadata like synchronization status. The same component stack is used to transport groupware data back to the device.<br />
<br />
=== Requirements ===<br />
<br />
Since the OXtender for Business Mobility is a server plug-in based on the OSGi Framework it can be added to an existing Open-Xchange installation very easily. '''Open-Xchange Server 6.16 or later is required to operate this extension.''' The OXtender for Business Mobility uses the resources and services offered by the Open-Xchange server, no additional software or configuration is required.<br />
<br />
* [[Open-Xchange_Installation_Guide_for_Debian_6.0 | Debian 6.0 (Squeeze)]]<br />
* [[Open-Xchange_Installation_Guide_for_SLES11 | SLES11]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL5 | RHEL5]]<br />
* [[Open-Xchange_Installation_Guide_for_RHEL6 | RHEL6]]<br />
<br />
'''Please Note:''' To get in favor of the latest minor features and bugfixes, you need to have a valid license. The article [[UpdatingOXPackages | Updating OX-Packages]] explains how that can be done.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-meta-mobility|sopath=OXtender-stable/BusinessMobilityOXtender|ldbaccount=LDBACCOUNT:LDBPASSWD|reponame=oxmobility}}<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/BusinessMobilityOXtender/ link] to download the User Manuals in different languages.<br />
<br />
<br />
Now the Open-Xchange groupware and admin service needs to be restarted:<br />
/etc/init.d/open-xchange-groupware restart<br />
/etc/init.d/open-xchange-admin restart<br />
<br />
On the first login after the restart, all required database tables will be created.<br />
<br />
== Configuration ==<br />
<br />
=== Mail Push ===<br />
<br />
In order to get mail push, either install and configure the package open-xchange-push-malpoll, which is not recommended on large deployments or if you're using cyrus-imap, read the [[MailNotify Bundle]] instructions on how to set up real mail push with cyrus.<br />
<br />
=== Open-Xchange configuration ===<br />
The configuration for USM and the EAS protocol can be found in these two configuration files:<br />
/opt/open-xchange/etc/groupware/usm.properties<br />
/opt/open-xchange/etc/groupware/eas.properties<br />
<br />
Make sure that the Open-Xchange Server URL is set properly in usm.properties. This needs to be the machine which provides the web interface. Usually, this is localhost, as the webserver and Open-Xchange run on the same machine.<br />
com.openexchange.usm.ox.url=http://localhost/ajax/<br />
<br />
in case webserver and Open-Xchange aren't running on the same machine:<br />
com.openexchange.usm.ox.url=http://$FQDN/ajax/<br />
(Where $FQDN is the fully qualified domain name of your frontend system)<br />
<br />
On clustered setups, adjust the file<br />
/opt/open-xchange/etc/groupware/noipcheck.cnf<br />
to include the range of IP addresses of the servers on which USM is running.<br />
<br />
<br />
Documentation about the configuration parameters can be found inside the configuration files. If you change any attribute at the configuration files, the Open-Xchange groupware service needs to be restarted.<br />
/etc/init.d/open-xchange-groupware restart<br />
<br />
=== Apache Configuration ===<br />
Mobile devices supporting ActiveSync use a special URL to communicate with an ActiveSync enabled Open-Xchange Server. This URL needs to be forwarded to the Open-Xchange ActiveSync servlet. When using Apache 2 and mod_proxy_ajp, this servlet can simply be added to the webservers proxy_ajp configuration:<br />
ProxyPass /Microsoft-Server-ActiveSync ajp://127.0.0.1:8009/Microsoft-Server-ActiveSync smax=0 ttl=60 retry=5<br />
<br />
The example assumes that Open-Xchange Server is running on the same machine like the webserver. Please refer the Open-Xchange administration documentation for more information about Apache configuration. Please restart apache after performing the configuration change.<br />
/etc/init.d/apache2 restart<br />
<br />
=== Enabling ActiveSync for user accounts ===<br />
In order to use synchronization through ActiveSync, this feature needs to be activated for user accounts. You can either activate it for specific users or a whole context.<br />
<br />
Activating ActiveSync for specific users:<br />
/opt/open-xchange/sbin/changeuser -c 1 -A oxadmin -P admin_password -u testuser --access-usm on --access-active-sync on<br />
<br />
Activating ActiveSync for a whole context:<br />
/opt/open-xchange/sbin/changecontext -c 1 -A oxadminmaster -P admin_master_password --access-usm on --access-active-sync on<br />
<br />
== Log files and issue tracking ==<br />
When facing problems with synchronization, there are several ways to get more information than provided via device or platform specific error codes.<br />
<br />
=== Open-Xchange Server logfile ===<br />
By default, the log output is non verbose. Only severe errors will be logged. To enable a more detailed log output, the logging mechanism needs to be configured. This depends on the used mechanism.<br />
<br />
=== Commons Logging ===<br />
This is the default logging mechanism. If the Open-Xchange Server log output is written to ''var/log/open-xchange/open-xchange.log'' it's an indicator that this mechanism is in use. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/file-logging.properties<br />
[...]<br />
com.openexchange.usm.level=FINE<br />
<br />
This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== Log4j ===<br />
If the package ''open-xchange-log4j'' is installed, Open-Xchange Server will log via a UDP network socket. In most cases a syslog daemon is listening to this socket and will write the log data to a platform specif file like ''/var/log/syslog''. To make the log output more verbose, add the following parameter:<br />
<br />
vim /opt/open-xchange/etc/groupware/log4j.xml<br />
[...]<br />
<category name="com.openexchange.usm"><br />
<level value="DEBUG"/><br />
<appender-ref ref="SERVER_LOG"/><br />
</category><br />
<br />
Please note that the XML syntax must be correct. This will enable a software debug log for all components using USM, including EAS after restarting Open-Xchange Server.<br />
<br />
=== EAS debug logfile ===<br />
While the generic Open-Xchange Server log file will keep track on errors reported by the software components, the EAS debug log file will print all data transfered to the device as XML. Please note: this log file may contain confidential data about the users personal groupware objects. Make sure that no unauthorized access to those log files is possible in order to maintain privacy. Change the configuration file accordingly and set a output path which can only accessed by authorized persons.<br />
<br />
vim /opt/open-xchange/etc/groupware/eas.properties<br />
[...]<br />
com.openexchange.usm.eas.debug_log=/tmp/EAS-debug.log<br />
<br />
This will enable a XML based debug log for all EAS connections, after restarting Open-Xchange Server.<br />
<br />
=== Network traffic ===<br />
When using unencrypted connections between the device and USM and USM and Open-Xchange Server (not recommended), it's possible to analyze the network traffic with tools like ngrep or wireshark. When using encrypted data connections using SSL, the transfered data can be decrypted using the corresponding private key. Please note that there are two network streams, one from the device to USM (external) and one from USM to OX (internal).<br />
<br />
== Bug-Reporting == <br />
Please report bugs via the Open-Xchange Bugzilla:<br />
<br />
[https://bugs.open-xchange.com/ Direct link to Open-Xchange Bugzilla]<br />
<br />
* Product: OXtender for Business Mobility<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX_EMail_Push_Introduction&diff=10357OX EMail Push Introduction2012-05-07T07:52:54Z<p>Thomas.siedentopf: typo</p>
<hr />
<div>= Introduction to EMail Push in Open-Xchange =<br />
<br />
== Abstract ==<br />
<br />
In combination with [[OXtender_for_Business_Mobility]] (EAS) and<br />
[[OXtender_2_for_Microsoft_Outlook]] (OLOX2) a working mail push is very<br />
important. It is important to know, that this is a combined<br />
requirement to the mail server and the Open-Xchange server to make<br />
that happen.<br />
<br />
Both of the listed OXtenders are accessing Open-Xchange via the USM<br />
interface (Universal Synchronization Module, which is the package<br />
open-xchange-usm).<br />
<br />
In summary:<br />
<br />
* '''EAS uses an internal mail poll if no push available'''<br />
* '''OLOX2 is depending on an external mail push trigger'''<br />
<br />
== Mail Push with [[OXtender_for_Business_Mobility]] ==<br />
<br />
In addition to an externally triggered mail push, in internal mail<br />
poll initiated by the usm module is executed.<br />
<br />
This is, how this polling can be influenced via<br />
<tt>/opt/open-xchange/etc/groupware/usm.properties</tt>:<br />
<br />
# <tt>com.openexchange.usm.session.sync.email_pull_delay=50%</tt><br />
# <tt>com.openexchange.usm.session.sync.email_pull_min_delay=60000</tt><br />
<br />
<br />
These values are the default values.<br />
<br />
1. defines, when an internal poll should be triggered while waiting<br />
for the client. This can be done as an absolute value (in<br />
milliseconds) or as a percentage value based on the waiting time as<br />
been specified by by the client per Active Sync Protocol (EAS). In the<br />
EAS protocol, the client specifies this time dynamically, usually<br />
between 30 seconds and 30 minutes. If an absolute time is specified<br />
here and the time set by the client is smaller, a mail poll is<br />
initiated at the end of the waiting time if not prevented by the<br />
setting of 2.<br />
<br />
<br />
2. defines an additional minimum waiting time, which is enforced to be<br />
followed, before an internal poll is executed. Is the value as<br />
specified by the EAS client/protocol smaller than this value, no poll<br />
will be executed. If 2. is set to a negative value, the internal mail<br />
polling of USM will be completely disabled.<br />
<br />
<br />
=== Examples ===<br />
<br />
==== A ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=50%<br />
com.openexchange.usm.session.sync.email_pull_min_delay=-1<br />
<br />
Internal mail poll is disabled.<br />
<br />
==== B ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=50%<br />
com.openexchange.usm.session.sync.email_pull_min_delay=60000<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
!Client waiting time<br />
!Mail polling interval<br />
|-<br />
|30 seconds<br />
|no polling<br />
|-<br />
|90 seconds<br />
|poll after 60 seconds (!)<br />
|-<br />
|180 seconds<br />
|poll after 90 seconds<br />
|-<br />
|1800 seconds<br />
|poll after 900 seconds<br />
|}<br />
<br />
==== C ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=120000<br />
com.openexchange.usm.session.sync.email_pull_min_delay=60000<br />
<br />
{| class="wikitable"<br />
|-<br />
!Client waiting time<br />
!Mail polling interval<br />
|-<br />
|30 seconds<br />
|no polling<br />
|-<br />
|90 seconds<br />
|poll after 90 seconds (!)<br />
|-<br />
|180 seconds<br />
|poll after 120 seconds<br />
|-<br />
|1800 seconds<br />
|poll after 120 seconds<br />
|}<br />
<br />
<br />
==== D ====<br />
<br />
com.openexchange.usm.session.sync.email_pull_delay=60000<br />
com.openexchange.usm.session.sync.email_pull_min_delay=120000<br />
<br />
{| class="wikitable"<br />
|-<br />
!Client waiting time<br />
!Mail polling interval<br />
|-<br />
|30 seconds<br />
|no polling<br />
|-<br />
|90 seconds<br />
|no polling (!)<br />
|-<br />
|180 seconds<br />
|poll after 120 seconds<br />
|-<br />
|1800 seconds<br />
|poll after 120 seconds<br />
|}<br />
<br />
<br />
This example is not usefull, it should show, that property 2. has a<br />
higher priority than property 1.<br />
<br />
<br />
The default behaviour can be described like shown below:<br />
<br />
client waiting time X (EAS Ping):<br />
X < 60 s -> no internal mail poll<br />
60 s <= X <= 120 s -> internal poll after 60 s<br />
120 s < X -> internal poll after X/2 s<br />
<br />
== Mail Push with [[OXtender_2_for_Microsoft_Outlook]] ==<br />
<br />
In OLOX2 USM does NO internal mail poll at all. There are no long<br />
running waiting requests (like with Ping in EAS). Instead, the client<br />
(Outlook OXtender) does http requests in short intervals asking for<br />
changes. This is the reason why USM does no internal mail poll but is<br />
depending on messages from the Open-Xchange server (using OSGi<br />
Events).<br />
The only exception is, when the client changes from one email folder to<br />
another one. This will initiate a sync.<br />
<br />
== Open-Xchange Mail Push implementations ==<br />
<br />
There are currently two publicly available implementations of mail push.<br />
<br />
=== The [[MailNotify_Bundle]] ===<br />
<br />
This package only integrates with cyrus-imapd at the moment. We prepared a plugin for<br />
dovecot2, but it's not part of the official upstream tarball. Please contact us if you are interested in it.<br />
<br />
=== The MALPoll Bundle ===<br />
<br />
The package '''open-xchange-push-malpoll''' simulates mail push in polling the imap server on a regular<br />
basis. This can only be recommended on small installations as it might stress the imap server.<br />
<br />
=== The [[MailPushIMAPIDLE Bundle]] ===<br />
<br />
'''New since latest 6.20 update!'''<br />
<br />
Mail push via IMAP IDLE.<br />
Works with all imap servers being able to do IMAP IDLE.</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=9964Caldav carddav Bundles2012-02-02T14:21:45Z<p>Thomas.siedentopf: </p>
<hr />
<div>= Installation CalDAV and CardDAV with Open-Xchange =<br />
<br />
OXtender for Mac OS X is discontinued due to the fact that the latest version of Apple OS X “Lion” no longer support Apple SyncServices, which synchronization with OXtender for Mac OS X was based on. To support synchronization between Open-Xchange Server and Mac OS X application, Open-Xchange implements synchronization functionality that is using CalDAV and CardDAV protocols. <br />
<br />
The new synchronization protocols are available and supported for all customers with a valid Open-Xchange license of Open-Xchange Server Edition and Open-Xchange Hosting Edition starting with Version 6.20.1 Rev5.<br />
<br />
== What are CalDAV and CardDAV? ==<br />
<br />
CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. Currently we support Mac OS X iCal and Addressbook in Mac OS X 10.6 and upward with these protocols. What do they do for a user? The CalDAV interface publishes all the users calendar via CalDAV so the user can subscribe to them in Mac OS X iCal program. Addressbook on the other hand is more limited, as it can only subscribe one contact folder. As an administrator you can either publish the standard contact folder plus the global addressbook or use the (equally new) contact aggregation feature to assemble and publish an aggregated folder containing all the address data visible for a given user in a context merged as best we can at this point. Depending on whether the open-xchange-contact-aggregator package is installed and activated, the first or second option is chosen. '''Note: The open-xchange-contact-aggregator bundle is optional and should be considered experimental'''<br />
<br />
== User Guide and Configuration ==<br />
'''Please find further information regarding the configuration at the [http://oxpedia.org/wiki/index.php?title=SetUpMacCalCardDAVClients User Guide]'''<br />
<br />
== Preparation ==<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
<br />
Please edit your file /etc/apache2/ox6.conf so that ''' the existing configuration for ox as well as the new configuration for CalDAV and CardDav are placed inside a virtual host '''.<br />
<br />
This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
$ vi /etc/apache2/ox6.conf <br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.MYSERVER.TLD<br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
</Proxy><br />
ProxyPass / ajp://localhost:8009/servlet/dav/ smax=0 ttl=60 retry=5<br />
</VirtualHost><br />
<br />
<VirtualHost *:80><br />
ServerName MYSERVER.TLD<br />
ServerAdmin webmaster@localhost<br />
DocumentRoot /var/www/<br />
<br />
<Directory /var/www/><br />
AllowOverride None<br />
Order allow,deny<br />
allow from all<br />
RedirectMatch ^/$ /ox6/<br />
Options +FollowSymLinks +SymLinksIfOwnerMatch<br />
</Directory><br />
# deflate<br />
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript<br />
<br />
# pre-compressed files<br />
AddType text/javascript .jsz<br />
AddType text/css .cssz<br />
AddType text/xml .xmlz<br />
AddType text/plain .po<br />
<br />
AddEncoding gzip .jsz .cssz .xmlz<br />
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip<br />
<br />
ExpiresActive On<br />
<br />
<Location /ox6><br />
# Expires (via ExpiresByType to override global settings)<br />
ExpiresByType image/gif "access plus 6 months"<br />
ExpiresByType image/png "access plus 6 months"<br />
ExpiresByType image/jpg "access plus 6 months"<br />
ExpiresByType image/jpeg "access plus 6 months"<br />
ExpiresByType text/css "access plus 6 months"<br />
ExpiresByType text/html "access plus 6 months"<br />
ExpiresByType text/xml "access plus 6 months"<br />
ExpiresByType text/javascript "access plus 6 months"<br />
ExpiresByType text/x-js "access plus 6 months"<br />
ExpiresByType application/x-javascript "access plus 6 months"<br />
ExpiresDefault "access plus 6 months"<br />
Header append Cache-Control "private"<br />
Header unset Last-Modified<br />
Header unset Vary<br />
# Strip version<br />
RewriteEngine On<br />
RewriteRule v=\w+/(.+) $1 [L]<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
<br />
<Location /ox6/ox.html><br />
ExpiresByType text/html "now"<br />
ExpiresDefault "now"<br />
Header unset Last-Modified<br />
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
<br />
<Location /ox6/index.html><br />
ExpiresByType text/html "now"<br />
ExpiresDefault "now"<br />
Header unset Last-Modified<br />
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
</VirtualHost><br />
<br />
If you use this method, you have to make sure that dav.MYSERVER.TLD is reachable, your dns configuration need an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to /tmp.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
<br />
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.<br />
<br />
$ vi /etc/apache2/ox6.conf<br />
<br />
RewriteEngine On <br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV <br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P]<br />
<br />
'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.<br />
<br />
== Which packages do I need? ==<br />
<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
* open-xchange-webdav-directory - Assembles the *DAV interfaces into a common tree. This is needed for publishing certain properties so clients accept the OX is a WebDAV Server.<br />
* open-xchange-webdav-acl - The WebDAV equivalent of the /ajax/user interface. Allows clients to discover the current and other users and their addressbooks and calendars.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
and optionally<br />
* open-xchange-contact-aggregator - Creates (and updates daily) a folder "all my contacts" in which all contacts a user can see are aggregated. This is very '''experimental''' and should be considered alpha state.<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
== Configuration ==<br />
<br />
'''CalDAV'''<br />
<br />
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
This means: In general CalDAV is turned off, but using the contextSets feature of the config cascade it is turned on for everyone that has infostore access.<br />
<br />
'''CardDAV'''<br />
<br />
Similarly to caldav the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:<br />
<br />
The property '''com.openexchange.carddav.ignoreFolders''' contains a blacklist of folders that will not be served via CalDAV. In large contexts in enterprise installations it might make sense to disable the global addressbook in CardDAV:<br />
<br />
com.openexchange.carddav.ignoreFolders=6<br />
<br />
'''Contact Aggregation'''<br />
<br />
The contact aggregator can be enabled by enabling the property '''com.openexchange.contact.aggregator.enabled'''. By default this is turned off. Installations in which the contact aggregation feature should be enabled, must switch this property to '''true'''.<br />
<br />
The contact aggregator knows how to do two kinds of aggregation runs. A '''fast run''' and a '''slow run'''. The fast run will collect all contacts from all folders a user can see, the slow run will, in addition, scour all email accounts for email addresses. Whether the system does these runs, and how often can be configured with the properties:<br />
<br />
'''com.openexchange.contact.aggregator.fastRunInterval'''<br />
and<br />
'''com.openexchange.contact.aggregator.slowRunInterval'''<br />
<br />
The value can be a number of milliseconds or an interval specification with ms for milliseconds, s for seconds, m for minutes, h for hours, d for days and w for weeks. For example, if you want to do the fast run once a day and the slow run once a week you could configure the following:<br />
<br />
com.openexchange.contact.aggregator.fastRunInterval=1d<br />
com.openexchange.contact.aggregator.slowRunInterval=1w<br />
<br />
By default, slow runs are deactivated, fast runs are performed once a day.<br />
<br />
In case you allow slow runs, the number of mails per mailfolder can be configured with the property:<br />
<br />
com.openexchange.contact.aggregator.mailLimit=3000<br />
<br />
As for CardDAV you can configure a list of folders that should not be part of an aggregation run with the property<br />
<br />
'''com.openexchange.contact.aggregator.folderBlacklist'''<br />
<br />
which can contain a comma separated blacklist of folderIds. <br />
<br />
To find out how to set up the Mac OS X clients, please see: [[SetUpMacCalCardDAVClients|Setting up CalDAV and CardDAV in Mac OS X]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Caldav_carddav_Bundles&diff=9963Caldav carddav Bundles2012-02-02T14:20:43Z<p>Thomas.siedentopf: changed support status ans wording around it</p>
<hr />
<div>= Installation CalDAV and CardDAV with Open-Xchange =<br />
<br />
OXtender for Mac OS X is discontinued due to the fact that the latest version of Apple OS X “Lion” no longer support Apple SyncServices, which synchronization with OXtender for Mac OS X was based on. To support synchronization between Open-Xchange Server and Mac OS X application, Open-Xchange implements synchronization functionality that is using CalDAV and CardDAV protocols. <br />
<br />
The new synchronization protocols are available and supported for all customers with a valid Open-Xchange license of Open-Xchange Server Edition and Open-Xchange Hosting Edition starting with Version 6.20.1 Rev5.<br />
<br />
== What are CalDAV and CardDAV? ==<br />
<br />
CalDAV and CardDAV are standard protocols for the exchange of calendar data and address data respectively. Currently we support Mac OS X iCal and Addressbook, in Mac OS X 10.6 and upward with these protocols. What do they do for a user? The CalDAV interface publishes all the users calendar via CalDAV so the user can subscribe to them in Mac OS X iCal program. Addressbook on the other hand is more limited, as it can only subscribe one contact folder. As an administrator you can either publish the standard contact folder plus the global addressbook or use the (equally new) contact aggregation feature to assemble and publish an aggregated folder containing all the address data visible for a given user in a context merged as best we can at this point. Depending on whether the open-xchange-contact-aggregator package is installed and activated, the first or second option is chosen. '''Note: The open-xchange-contact-aggregator bundle is optional and should be considered experimental'''<br />
<br />
== User Guide and Configuration ==<br />
'''Please find further information regarding the configuration at the [http://oxpedia.org/wiki/index.php?title=SetUpMacCalCardDAVClients User Guide]'''<br />
<br />
== Preparation ==<br />
<br />
=== Alternative 1: Apache vhost (recommended) ===<br />
<br />
Please edit your file /etc/apache2/ox6.conf so that ''' the existing configuration for ox as well as the new configuration for CalDAV and CardDav are placed inside a virtual host '''.<br />
<br />
This is an <b>example</b> where MYSERVER.TLD is the domain-name of the ox-server:<br />
<br />
$ vi /etc/apache2/ox6.conf <br />
<br />
NameVirtualHost *:80<br />
<VirtualHost *:80><br />
ServerName dav.MYSERVER.TLD<br />
ErrorLog /tmp/dav.err.log<br />
TransferLog /tmp/dav.access.log<br />
<Proxy /><br />
Order allow,deny<br />
Allow from all<br />
</Proxy><br />
ProxyPass / ajp://localhost:8009/servlet/dav/ smax=0 ttl=60 retry=5<br />
</VirtualHost><br />
<br />
<VirtualHost *:80><br />
ServerName MYSERVER.TLD<br />
ServerAdmin webmaster@localhost<br />
DocumentRoot /var/www/<br />
<br />
<Directory /var/www/><br />
AllowOverride None<br />
Order allow,deny<br />
allow from all<br />
RedirectMatch ^/$ /ox6/<br />
Options +FollowSymLinks +SymLinksIfOwnerMatch<br />
</Directory><br />
# deflate<br />
AddOutputFilterByType DEFLATE text/html text/plain text/javascript application/javascript text/css text/xml application/xml text/x-js application/x-javascript<br />
<br />
# pre-compressed files<br />
AddType text/javascript .jsz<br />
AddType text/css .cssz<br />
AddType text/xml .xmlz<br />
AddType text/plain .po<br />
<br />
AddEncoding gzip .jsz .cssz .xmlz<br />
SetEnvIf Request_URI "\.(jsz|cssz|xmlz)$" no-gzip<br />
<br />
ExpiresActive On<br />
<br />
<Location /ox6><br />
# Expires (via ExpiresByType to override global settings)<br />
ExpiresByType image/gif "access plus 6 months"<br />
ExpiresByType image/png "access plus 6 months"<br />
ExpiresByType image/jpg "access plus 6 months"<br />
ExpiresByType image/jpeg "access plus 6 months"<br />
ExpiresByType text/css "access plus 6 months"<br />
ExpiresByType text/html "access plus 6 months"<br />
ExpiresByType text/xml "access plus 6 months"<br />
ExpiresByType text/javascript "access plus 6 months"<br />
ExpiresByType text/x-js "access plus 6 months"<br />
ExpiresByType application/x-javascript "access plus 6 months"<br />
ExpiresDefault "access plus 6 months"<br />
Header append Cache-Control "private"<br />
Header unset Last-Modified<br />
Header unset Vary<br />
# Strip version<br />
RewriteEngine On<br />
RewriteRule v=\w+/(.+) $1 [L]<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
<br />
<Location /ox6/ox.html><br />
ExpiresByType text/html "now"<br />
ExpiresDefault "now"<br />
Header unset Last-Modified<br />
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
<br />
<Location /ox6/index.html><br />
ExpiresByType text/html "now"<br />
ExpiresDefault "now"<br />
Header unset Last-Modified<br />
Header set Cache-Control "no-store, no-cache, must-revalidate, post-check=0, pre-check=0"<br />
# Turn off ETag<br />
Header unset ETag<br />
FileETag None<br />
</Location><br />
</VirtualHost><br />
<br />
If you use this method, you have to make sure that dav.MYSERVER.TLD is reachable, your dns configuration need an entry for this name. Take care of the the dav.* logfiles, the example writes them without logrotation to /tmp.<br />
<br />
=== Alternative 2: Apache useragent detection ===<br />
<br />
For environments where it is inconvenient to setup a vhost there is the possibility to redirect to relevant servlets another way: Via useragent detection. This is not recommended for the following reason: Per definition this is a whitelist-approach and any client sending a useragent-string not explicitly listed in the configuration will not be able to connect . Useragent-strings may also change between different versions of an application or may even be actively changed into something non-standard.<br />
<br />
$ vi /etc/apache2/ox6.conf<br />
<br />
RewriteEngine On <br />
RewriteCond %{HTTP_USER_AGENT} AddressBook [OR]<br />
RewriteCond %{HTTP_USER_AGENT} Address%20Book [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CalendarStore [OR]<br />
RewriteCond %{HTTP_USER_AGENT} CoreDAV <br />
RewriteRule (.*) ajp://localhost:8009/servlet/dav$1 [P]<br />
<br />
'''Note:''' The address book app on OSX 10.6 uses a localized user-agent string. If you're expecting clients with non-english language settings, you need to add the translated user-agent string to these rewrite rules. For example: "Adressbuch" for german OSX clients.<br />
<br />
== Which packages do I need? ==<br />
<br />
To get CalDAV and CardDAV up and running you need the following packages:<br />
<br />
* open-xchange-webdav-directory - Assembles the *DAV interfaces into a common tree. This is needed for publishing certain properties so clients accept the OX is a WebDAV Server.<br />
* open-xchange-webdav-acl - The WebDAV equivalent of the /ajax/user interface. Allows clients to discover the current and other users and their addressbooks and calendars.<br />
* open-xchange-carddav - The CardDAV interface exposing the users addressbook via carddav<br />
* open-xchange-caldav - The CalDAV inteface exposing the users calendars via caldav<br />
<br />
and optionally<br />
* open-xchange-contact-aggregator - Creates (and updates daily) a folder "all my contacts" in which all contacts a user can see are aggregated. This is very '''experimental''' and should be considered alpha state.<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-caldav open-xchange-carddav open-xchange-webdav-acl open-xchange-webdav-directory |sopath=updates}}<br />
<br />
== Configuration ==<br />
<br />
'''CalDAV'''<br />
<br />
The property '''com.openexchange.caldav.enabled''' governs whether a user has access to the CalDAV interface. This can be configured along the config cascade, in the default setting, everyone that has access to the infostore also has access to caldav. This is achieved in the following way:<br />
<br />
/opt/open-xchange/etc/groupware/caldav.properties:<br />
com.openexchange.caldav.enabled=false<br />
<br />
/opt/open-xchange/etc/groupware/contextSets/caldav.yml<br />
premium:<br />
com.openexchange.caldav.enabled: true<br />
withTags: ucInfostore<br />
<br />
This means: In general CalDAV is turned off, but using the contextSets feature of the config cascade it is turned on for everyone that has infostore access.<br />
<br />
'''CardDAV'''<br />
<br />
Similarly to caldav the property '''com.openexchange.carddav.enabled''' governs whether CardDAV is available for a certain user. This is configured exactly like CalDAV with the config cascade only enabling this for users that have access to the infostore:<br />
<br />
The property '''com.openexchange.carddav.ignoreFolders''' contains a blacklist of folders that will not be served via CalDAV. In large contexts in enterprise installations it might make sense to disable the global addressbook in CardDAV:<br />
<br />
com.openexchange.carddav.ignoreFolders=6<br />
<br />
'''Contact Aggregation'''<br />
<br />
The contact aggregator can be enabled by enabling the property '''com.openexchange.contact.aggregator.enabled'''. By default this is turned off. Installations in which the contact aggregation feature should be enabled, must switch this property to '''true'''.<br />
<br />
The contact aggregator knows how to do two kinds of aggregation runs. A '''fast run''' and a '''slow run'''. The fast run will collect all contacts from all folders a user can see, the slow run will, in addition, scour all email accounts for email addresses. Whether the system does these runs, and how often can be configured with the properties:<br />
<br />
'''com.openexchange.contact.aggregator.fastRunInterval'''<br />
and<br />
'''com.openexchange.contact.aggregator.slowRunInterval'''<br />
<br />
The value can be a number of milliseconds or an interval specification with ms for milliseconds, s for seconds, m for minutes, h for hours, d for days and w for weeks. For example, if you want to do the fast run once a day and the slow run once a week you could configure the following:<br />
<br />
com.openexchange.contact.aggregator.fastRunInterval=1d<br />
com.openexchange.contact.aggregator.slowRunInterval=1w<br />
<br />
By default, slow runs are deactivated, fast runs are performed once a day.<br />
<br />
In case you allow slow runs, the number of mails per mailfolder can be configured with the property:<br />
<br />
com.openexchange.contact.aggregator.mailLimit=3000<br />
<br />
As for CardDAV you can configure a list of folders that should not be part of an aggregation run with the property<br />
<br />
'''com.openexchange.contact.aggregator.folderBlacklist'''<br />
<br />
which can contain a comma separated blacklist of folderIds. <br />
<br />
To find out how to set up the Mac OS X clients, please see: [[SetUpMacCalCardDAVClients|Setting up CalDAV and CardDAV in Mac OS X]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:Open-Xchange_Mac_OXtender_Installation_Guide&diff=9962OX6:Open-Xchange Mac OXtender Installation Guide2012-02-02T14:09:36Z<p>Thomas.siedentopf: </p>
<hr />
<div>{{DEPRECATED}}<br />
This page is DEPRECATED. For using Open-Xchange with Mac OS X iCal and AddressBook please goto [[SetUpMacCalCardDAVClients]]<br />
== Information and Installation of OXtender for Mac OS X ==<br />
<br />
== Description ==<br />
<br />
The OXtender for Mac OS X synchronizes Open-Xchange Server 6 with your Mac OS X computer. Data of the following modules will be synchronized: <br />
* Calendar<br />
* Contacts<br />
* Task<br />
<br />
In addition, it enables the InfoStore files to be accessed as Network Volume.<br />
<br />
== Components ==<br />
<br />
Calendar, Contacts and Tasks: Objects will be regular synchronized via SyncServices. The following folders will be synchronized <br />
* Contacts - Private Address book and the Public Address book<br />
* Tasks - Private Tasks<br />
* Calendar - Private Calendar<br />
<br />
If the user changes any data on their Mac OS X, the synchronization will be started after a 10 seconds waiting time via "Trickle-Sync".<br />
<br />
== Requirements ==<br />
<br />
* Mac OS X 10.5 <br />
* 26 MByte of storage space<br />
* Open-Xchange Server 6 SP4 Update 1 build 6610 or higher<br />
<br />
The OXtender for Mac OS X is available for all customers with a Open-Xchange Hosting Edition, Open-Xchange Server Edition and Open-Xchange Appliance Edition Maintenance.<br />
<br />
== Download ==<br />
<br />
Follow this [http://software.open-xchange.com/OX6/OXtender-stable/MacOXtender/ link] to download the Installation package and the Release Notes. (The LDB credentials have to be provided)<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/Mac-OXtender/ link] to download the User Manuals in different languages.<br />
<br />
== Installation ==<br />
<br />
* After the download of the package, you can start the installation by double-clicking on the package. You will then be asked for your administrator password. On the first screen, you will see some information about the MacOXtender. Please follow the installation steps at the wizard. <br />
* Please read carefully the license agreement for Open-Xchange.<br />
<br />
== Configuration ==<br />
<br />
* After the installation of the OXtender for Mac OS X, the user will find an Open-Xchange setting "OX Connector" in the System Preferences application of your Mac.<br />
* Please click on the OX icon. This will open the configuration dialog.<br />
* Please enter your synchronization details at the tab "User Account". You have to enter the server address, user account and password for the Open-Xchange Server.<br />
* On the second tab, you can change your synchronization settings for MacOXtender. Besides the setting "Slow-Sync" to compare the data on the Server and your Mac OS X, you can overwrite the data on the Server. Also, it is possible to restore the changed settings.<br />
* The first time the OXtender runs, a pop-up will appear and ask whether Python may use the key "oxsync". Answer "yes" to that.<br />
* The OXtender will start at once. The orange circle on the OXtender icon indicates that it is running.<br />
<br />
== Uninstalling a previous OXtender version ==<br />
<br />
The OXtender for Mac OS X comes with a program for uninstalling it. Just double-click on the respective entry and the program launches. <br />
<br />
Now you can install the new OXtender as described above.<br />
<br />
== Reporting of Bugs ==<br />
<br />
Please report Bugs and missing features via the [http://bugs.open-xchange.com/cgi-bin/bugzilla/enter_bug.cgi?product=OXtender%20for%20Mac%20OS%20X Open-Xchange Bugzilla]. Many thanks in advance for your support.<br />
<br />
== Further Information for Synchronization and Limitations==<br />
<br />
Synchronization is a complex topic, ripe with synchronization errors and weird behavior. You will find further information for the Synchronization and Limitations at the [http://software.open-xchange.com/OX6/doc/Mac-OXtender/ User Manual]<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:Open-Xchange_Mac_OXtender_Installation_Guide&diff=9961OX6:Open-Xchange Mac OXtender Installation Guide2012-02-02T14:08:08Z<p>Thomas.siedentopf: deprecated. redirecting to CalDAV CardDAV article</p>
<hr />
<div>{{DEPRECATED}}<br />
This page is DEPRECATED. For using OX6 with Mac OS X iCal and AddressBook please goto [[SetUpMacCalCardDAVClients]]<br />
== Information and Installation of OXtender for Mac OS X ==<br />
<br />
== Description ==<br />
<br />
The OXtender for Mac OS X synchronizes Open-Xchange Server 6 with your Mac OS X computer. Data of the following modules will be synchronized: <br />
* Calendar<br />
* Contacts<br />
* Task<br />
<br />
In addition, it enables the InfoStore files to be accessed as Network Volume.<br />
<br />
== Components ==<br />
<br />
Calendar, Contacts and Tasks: Objects will be regular synchronized via SyncServices. The following folders will be synchronized <br />
* Contacts - Private Address book and the Public Address book<br />
* Tasks - Private Tasks<br />
* Calendar - Private Calendar<br />
<br />
If the user changes any data on their Mac OS X, the synchronization will be started after a 10 seconds waiting time via "Trickle-Sync".<br />
<br />
== Requirements ==<br />
<br />
* Mac OS X 10.5 <br />
* 26 MByte of storage space<br />
* Open-Xchange Server 6 SP4 Update 1 build 6610 or higher<br />
<br />
The OXtender for Mac OS X is available for all customers with a Open-Xchange Hosting Edition, Open-Xchange Server Edition and Open-Xchange Appliance Edition Maintenance.<br />
<br />
== Download ==<br />
<br />
Follow this [http://software.open-xchange.com/OX6/OXtender-stable/MacOXtender/ link] to download the Installation package and the Release Notes. (The LDB credentials have to be provided)<br />
<br />
Follow this [http://software.open-xchange.com/OX6/doc/Mac-OXtender/ link] to download the User Manuals in different languages.<br />
<br />
== Installation ==<br />
<br />
* After the download of the package, you can start the installation by double-clicking on the package. You will then be asked for your administrator password. On the first screen, you will see some information about the MacOXtender. Please follow the installation steps at the wizard. <br />
* Please read carefully the license agreement for Open-Xchange.<br />
<br />
== Configuration ==<br />
<br />
* After the installation of the OXtender for Mac OS X, the user will find an Open-Xchange setting "OX Connector" in the System Preferences application of your Mac.<br />
* Please click on the OX icon. This will open the configuration dialog.<br />
* Please enter your synchronization details at the tab "User Account". You have to enter the server address, user account and password for the Open-Xchange Server.<br />
* On the second tab, you can change your synchronization settings for MacOXtender. Besides the setting "Slow-Sync" to compare the data on the Server and your Mac OS X, you can overwrite the data on the Server. Also, it is possible to restore the changed settings.<br />
* The first time the OXtender runs, a pop-up will appear and ask whether Python may use the key "oxsync". Answer "yes" to that.<br />
* The OXtender will start at once. The orange circle on the OXtender icon indicates that it is running.<br />
<br />
== Uninstalling a previous OXtender version ==<br />
<br />
The OXtender for Mac OS X comes with a program for uninstalling it. Just double-click on the respective entry and the program launches. <br />
<br />
Now you can install the new OXtender as described above.<br />
<br />
== Reporting of Bugs ==<br />
<br />
Please report Bugs and missing features via the [http://bugs.open-xchange.com/cgi-bin/bugzilla/enter_bug.cgi?product=OXtender%20for%20Mac%20OS%20X Open-Xchange Bugzilla]. Many thanks in advance for your support.<br />
<br />
== Further Information for Synchronization and Limitations==<br />
<br />
Synchronization is a complex topic, ripe with synchronization errors and weird behavior. You will find further information for the Synchronization and Limitations at the [http://software.open-xchange.com/OX6/doc/Mac-OXtender/ User Manual]<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility&diff=9806OXtender for Business Mobility2012-01-03T14:10:18Z<p>Thomas.siedentopf: added Windows Phone 7 section</p>
<hr />
<div>= OXtender for Business Mobility =<br />
* [[OX_Product_Matrix#OXtender_for_Business_Mobility_-_Supported_Platforms|Overview]]<br />
<br />
== Server configuration ==<br />
* [[OXtender_for_Business_Mobility_Installation_Guide|Installation of the OXtender for Business Mobility]]<br />
* [[Quick_install_guide_for_OXSEforUCS_Mobility_OXtender_EN|Installation Guide Mobility OXtender for OX ASE / OX SE for UCS (English version)]]<br />
<br />
== Client configuration ==<br />
* [[OXtender_for_Business_Mobility_WinPhone7 | Windows Phone 7]]<br />
* [[OXtender_for_Business_Mobility_WinMob | Windows Mobile]]<br />
* [[OXtender_for_Business_Mobility_iPhone | iPhone]]<br />
* [[OXtender_for_Business_Mobility_BlackBerry | BlackBerry]]<br />
* [[OXtender_for_Business_Mobility_Nokia | Nokia S60]]<br />
* [[OXtender_for_Business_Mobility_Android | Android ]]<br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Enable_TinyMCE_spellcheck_module&diff=9760Enable TinyMCE spellcheck module2011-12-13T10:48:27Z<p>Thomas.siedentopf: /* Setting the default spell check language */</p>
<hr />
<div>= Introduction =<br />
<br />
By default there is no spell check available in the Open-Xchange application itself because most of the modern browsers usually offer a spellcheck module. TinyMCE, the HTML editor which is used by Open-Xchange for HTML editing while writing an eMail, offers a wide set of functions and features which can be added to the HTML editor UI. This example will describe how you can enable the TinyMCE based spellcheck functionality within the Open-Xchange mail module.<br />
<br />
= Requirements =<br />
<br />
* An installed Open-Xchange Server<br />
<br />
* ASpell with the according dictionaries needs to be installed<br />
<br />
* PHP5 must be enabled in your Apache configuration<br />
<br />
= Installation and Configuration of the TinyMCE Spellcheck module =<br />
<br />
Please note: Open-Xchange cannot support the spellcheck module itself and the according infrastructure (aspell, PHP), as those modules won't be maintained and tracked by Open-Xchange. On machines with lot of users this service may produce heavy load due to many request so we highly recommend to cluster it or, even better, to use the native spellcheck plugins of modern browsers.<br />
<br />
== Installation of the TinyMCE spellchecker module ==<br />
<br />
Please visit the TinyMCE website and download the latest TinyMCE "PHP Spellchecker" plugin at http://www.tinymce.com/download/download.php (at the bottom of the list). This article uses Version 2.0.5.<br />
<br />
Extract the downloaded archive and move the extracted directory "spellchecker" to the TinyMCE location on the Open-Xchange installation:<br />
<br />
$ mv spellchecker /var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/.<br />
<br />
== Enable the spellchecker button in the Open-Xchange HTML editor ==<br />
<br />
This can be accomplished by adding a properties file to directory "/opt/open-xchange/etc/groupware/settings".<br />
<br />
$ vim /opt/open-xchange/etc/groupware/settings/spellchecker.properties<br />
<br />
modules/mail/spellcheck=true<br />
<br />
== Setting the default spell check language ==<br />
<br />
The spell check language for the tinyMCE spellcheck module defaults to english and is configured inside the files editor_plugin.js and editor_plugin_src.js located in the directory<br />
/var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/spellchecker. A '+' character in front of the language name will indicate that this will be the default language used for the spellchecker. The default value for this option is '+English=en'. You can change this to another language by moving the '+' character in front of the language name of your choice in both files. Search for 'spellchecker_languages' to easily jump to the languages section in these files. The changes are active immediately after you have cleared your browser cache.<br />
<br />
== Setup the backend communication ==<br />
<br />
Finally we need to tell the spellchecker module which binary it should execute in order to get spelling suggestions. By default GoogleSpell is activated for remote suggestion, but as this would mean that every eMail which should be checked will be send to Google, we recommend to use a local aspell instance for this purpose. To do so, install aspell and the according dictionaries as we told you in the requirements section, and modify /var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/spellchecker/config.php to specify the aspell binary location. Please use the following example, and just replace [REPLACE_WITH_PATH_TO_ASPELL_BIN] with the location of the aspell binary (for example /usr/bin/aspell):<br />
<br />
<?php<br />
/**<br />
* config.php<br />
*<br />
* @package MCManager.includes<br />
*/<br />
// General settings<br />
//$config['general.engine'] = 'GoogleSpell';<br />
//$config['general.engine'] = 'PSpell';<br />
$config['general.engine'] = 'PSpellShell';<br />
//$config['general.remote_rpc_url'] = 'http://some.other.site/some/url/rpc.php';<br />
<br />
// PSpell settings<br />
$config['PSpell.mode'] = PSPELL_FAST;<br />
$config['PSpell.spelling'] = "";<br />
$config['PSpell.jargon'] = "";<br />
$config['PSpell.encoding'] = "";<br />
<br />
// PSpellShell settings<br />
$config['PSpellShell.mode'] = PSPELL_FAST;<br />
$config['PSpellShell.aspell'] = '[REPLACE_WITH_PATH_TO_ASPELL_BIN]'; // e.g. /usr/bin/aspell<br />
$config['PSpellShell.tmp'] = '/tmp';<br />
<br />
// Windows PSpellShell settings<br />
//$config['PSpellShell.aspell'] = '"c:\Program Files\Aspell\bin\aspell.exe"';<br />
//$config['PSpellShell.tmp'] = 'c:/temp';<br />
?> <br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Enable_TinyMCE_spellcheck_module&diff=9759Enable TinyMCE spellcheck module2011-12-13T10:48:07Z<p>Thomas.siedentopf: /* Setting the default spell check language */</p>
<hr />
<div>= Introduction =<br />
<br />
By default there is no spell check available in the Open-Xchange application itself because most of the modern browsers usually offer a spellcheck module. TinyMCE, the HTML editor which is used by Open-Xchange for HTML editing while writing an eMail, offers a wide set of functions and features which can be added to the HTML editor UI. This example will describe how you can enable the TinyMCE based spellcheck functionality within the Open-Xchange mail module.<br />
<br />
= Requirements =<br />
<br />
* An installed Open-Xchange Server<br />
<br />
* ASpell with the according dictionaries needs to be installed<br />
<br />
* PHP5 must be enabled in your Apache configuration<br />
<br />
= Installation and Configuration of the TinyMCE Spellcheck module =<br />
<br />
Please note: Open-Xchange cannot support the spellcheck module itself and the according infrastructure (aspell, PHP), as those modules won't be maintained and tracked by Open-Xchange. On machines with lot of users this service may produce heavy load due to many request so we highly recommend to cluster it or, even better, to use the native spellcheck plugins of modern browsers.<br />
<br />
== Installation of the TinyMCE spellchecker module ==<br />
<br />
Please visit the TinyMCE website and download the latest TinyMCE "PHP Spellchecker" plugin at http://www.tinymce.com/download/download.php (at the bottom of the list). This article uses Version 2.0.5.<br />
<br />
Extract the downloaded archive and move the extracted directory "spellchecker" to the TinyMCE location on the Open-Xchange installation:<br />
<br />
$ mv spellchecker /var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/.<br />
<br />
== Enable the spellchecker button in the Open-Xchange HTML editor ==<br />
<br />
This can be accomplished by adding a properties file to directory "/opt/open-xchange/etc/groupware/settings".<br />
<br />
$ vim /opt/open-xchange/etc/groupware/settings/spellchecker.properties<br />
<br />
modules/mail/spellcheck=true<br />
<br />
== Setting the default spell check language ==<br />
<br />
The spell check language for the tinyMCE spellcheck module defaults to english and is configured inside the files editor_plugin.js and editor_plugin_src.js located in the directory<br />
/var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/spellchecker. A '+' character in front of the language name will indicate that this will be the default language used for the spellchecker. The default value for this option is '+English=en'. You can change this to another language by moving the '+' character in front of the language name of your choice in both files. Search for 'spellchecker_languages' to easily jump to the languages section in these files. The changes are active immediately after you have cleared your browers cache.<br />
<br />
== Setup the backend communication ==<br />
<br />
Finally we need to tell the spellchecker module which binary it should execute in order to get spelling suggestions. By default GoogleSpell is activated for remote suggestion, but as this would mean that every eMail which should be checked will be send to Google, we recommend to use a local aspell instance for this purpose. To do so, install aspell and the according dictionaries as we told you in the requirements section, and modify /var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/spellchecker/config.php to specify the aspell binary location. Please use the following example, and just replace [REPLACE_WITH_PATH_TO_ASPELL_BIN] with the location of the aspell binary (for example /usr/bin/aspell):<br />
<br />
<?php<br />
/**<br />
* config.php<br />
*<br />
* @package MCManager.includes<br />
*/<br />
// General settings<br />
//$config['general.engine'] = 'GoogleSpell';<br />
//$config['general.engine'] = 'PSpell';<br />
$config['general.engine'] = 'PSpellShell';<br />
//$config['general.remote_rpc_url'] = 'http://some.other.site/some/url/rpc.php';<br />
<br />
// PSpell settings<br />
$config['PSpell.mode'] = PSPELL_FAST;<br />
$config['PSpell.spelling'] = "";<br />
$config['PSpell.jargon'] = "";<br />
$config['PSpell.encoding'] = "";<br />
<br />
// PSpellShell settings<br />
$config['PSpellShell.mode'] = PSPELL_FAST;<br />
$config['PSpellShell.aspell'] = '[REPLACE_WITH_PATH_TO_ASPELL_BIN]'; // e.g. /usr/bin/aspell<br />
$config['PSpellShell.tmp'] = '/tmp';<br />
<br />
// Windows PSpellShell settings<br />
//$config['PSpellShell.aspell'] = '"c:\Program Files\Aspell\bin\aspell.exe"';<br />
//$config['PSpellShell.tmp'] = 'c:/temp';<br />
?> <br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Enable_TinyMCE_spellcheck_module&diff=9758Enable TinyMCE spellcheck module2011-12-13T10:43:18Z<p>Thomas.siedentopf: /* Installation and Configuration of the TinyMCE Spellcheck module */</p>
<hr />
<div>= Introduction =<br />
<br />
By default there is no spell check available in the Open-Xchange application itself because most of the modern browsers usually offer a spellcheck module. TinyMCE, the HTML editor which is used by Open-Xchange for HTML editing while writing an eMail, offers a wide set of functions and features which can be added to the HTML editor UI. This example will describe how you can enable the TinyMCE based spellcheck functionality within the Open-Xchange mail module.<br />
<br />
= Requirements =<br />
<br />
* An installed Open-Xchange Server<br />
<br />
* ASpell with the according dictionaries needs to be installed<br />
<br />
* PHP5 must be enabled in your Apache configuration<br />
<br />
= Installation and Configuration of the TinyMCE Spellcheck module =<br />
<br />
Please note: Open-Xchange cannot support the spellcheck module itself and the according infrastructure (aspell, PHP), as those modules won't be maintained and tracked by Open-Xchange. On machines with lot of users this service may produce heavy load due to many request so we highly recommend to cluster it or, even better, to use the native spellcheck plugins of modern browsers.<br />
<br />
== Installation of the TinyMCE spellchecker module ==<br />
<br />
Please visit the TinyMCE website and download the latest TinyMCE "PHP Spellchecker" plugin at http://www.tinymce.com/download/download.php (at the bottom of the list). This article uses Version 2.0.5.<br />
<br />
Extract the downloaded archive and move the extracted directory "spellchecker" to the TinyMCE location on the Open-Xchange installation:<br />
<br />
$ mv spellchecker /var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/.<br />
<br />
== Enable the spellchecker button in the Open-Xchange HTML editor ==<br />
<br />
This can be accomplished by adding a properties file to directory "/opt/open-xchange/etc/groupware/settings".<br />
<br />
$ vim /opt/open-xchange/etc/groupware/settings/spellchecker.properties<br />
<br />
modules/mail/spellcheck=true<br />
<br />
== Setting the default spell check language ==<br />
<br />
The spell check language for the tinyMCE spellcheck module defaults to english and is configured inside the files editor_plugin.js and editor_plugin_src.js located in the directory<br />
/var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/spellchecker. A '+' character in front of the language name will indicate that this will be the default language used for the spellchecker. The default value for this option is '+English=en'. You can change this to another language by moving the '+' character in front of the language name of your choice in both files. Search for 'spellchecker_languages' to easily jump to the languages section in these files.<br />
<br />
== Setup the backend communication ==<br />
<br />
Finally we need to tell the spellchecker module which binary it should execute in order to get spelling suggestions. By default GoogleSpell is activated for remote suggestion, but as this would mean that every eMail which should be checked will be send to Google, we recommend to use a local aspell instance for this purpose. To do so, install aspell and the according dictionaries as we told you in the requirements section, and modify /var/www/ox6/3rdparty/tinymce/jscripts/tiny_mce/plugins/spellchecker/config.php to specify the aspell binary location. Please use the following example, and just replace [REPLACE_WITH_PATH_TO_ASPELL_BIN] with the location of the aspell binary (for example /usr/bin/aspell):<br />
<br />
<?php<br />
/**<br />
* config.php<br />
*<br />
* @package MCManager.includes<br />
*/<br />
// General settings<br />
//$config['general.engine'] = 'GoogleSpell';<br />
//$config['general.engine'] = 'PSpell';<br />
$config['general.engine'] = 'PSpellShell';<br />
//$config['general.remote_rpc_url'] = 'http://some.other.site/some/url/rpc.php';<br />
<br />
// PSpell settings<br />
$config['PSpell.mode'] = PSPELL_FAST;<br />
$config['PSpell.spelling'] = "";<br />
$config['PSpell.jargon'] = "";<br />
$config['PSpell.encoding'] = "";<br />
<br />
// PSpellShell settings<br />
$config['PSpellShell.mode'] = PSPELL_FAST;<br />
$config['PSpellShell.aspell'] = '[REPLACE_WITH_PATH_TO_ASPELL_BIN]'; // e.g. /usr/bin/aspell<br />
$config['PSpellShell.tmp'] = '/tmp';<br />
<br />
// Windows PSpellShell settings<br />
//$config['PSpellShell.aspell'] = '"c:\Program Files\Aspell\bin\aspell.exe"';<br />
//$config['PSpellShell.tmp'] = 'c:/temp';<br />
?> <br />
<br />
[[Category: OX6]]</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=OX6:Gui_Theming_Description&diff=9178OX6:Gui Theming Description2011-10-14T11:11:22Z<p>Thomas.siedentopf: fixed typo</p>
<hr />
<div>= Introduction =<br />
<br />
The Open-Xchange application allows you to create your own theme with your own colors and images. This tutorial will explain each step to create such theme.<br />
<br />
== Tools ==<br />
<br />
A good tool for testing, debugging and experimenting is the Firefox plug-in Firebug. This powerful plug-in can help you to debug your CSS elements on the fly. You also require a image manipulation program like Photoshop, Gimp or Corel Draw.<br />
<br />
== Understanding CSS ==<br />
<br />
The full layout of each Open-Xchange theme consists of two major parts: the CSS elements (90%) and the layout images (10%). This means, most of the theme is done in CSS. The main structure of the Open-Xchange frontend is done in HTML and combined with a CSS theme and a set of images completes the theme. The CSS elements control the look, size, position and sometimes the effect of a HTML element. If you want to change these attributes of a HTML element, you only need to define a class within you CSS file for this given HTML element. In this class, you can set the color, the size, the position and sometimes the effect of one or more HTML elements.<br />
<br />
Some HTML elements have a fixed group of attributes which are set in a CSS file which is not part of the Open-Xchange theme. These fixed parts are required to make the layout work correct. However, you can always override these attributes in your CSS file if you want to or if you need to. <br />
<br />
== Where to start ==<br />
<br />
All themes will be stored in the following directory of the Open-Xchange Server:<br />
<br />
/var/www/ox6/themes/<br />
<br />
Per default you will have at least two themes in this directory: a default theme and a alternative theme. The easiest way to start with your own theme is to copy the default theme with:<br />
<br />
cp -r /var/www/ox6/themes/default /var/www/ox6/themes/[YOUR_THEME_NAME]<br />
<br />
Now, you should start modifying your theme, by editing the stylesheet files in /var/www/ox6/themes/[YOUR_THEME_NAME]/css, and exchanging the images from /var/www/ox6/themes/[YOUR_THEME_NAME]/images. The following screenshots will give you an overview of the stylesheet structure, and which tags have to be modified in order to get your theme customized<br />
<br />
= Version 6.18.2 =<br />
<br />
== Setup description ==<br />
<br />
After you have created your theme, you should make this theme available in the configuration interface for users of the Open-Xchange Server. To do that, you only have to manifest your theme in the following server configuration file, afterwards your users can select your theme:<br />
<br />
groupware/settings/themes.properties<br />
<br />
You will find at least two already existing themes there. Just add your new theme. We call our new theme "Mantis" which is also the path within the theme folder of the GUI.<br />
<br />
modules/themes/mantis=Mantis<br />
<br />
Afterwards, restart the Open-Xchange service groupware. Your users can now select your theme.<br />
<br />
== Getting started, the background and the shadow ==<br />
<br />
Lets start with the basics, the background and the shadows. Open the global.css and change the background color:<br />
<br />
body {<br />
'''background-color: #f1f1f1;'''<br />
font-family: Arial, Helvetica, sans-serif;<br />
font-size: 9pt;<br />
color:#000;<br />
}<br />
<br />
Save the file and reload your theme.<br />
<br />
[[Image:Background_theming.png|thumb|150px|none|Background]]<br />
<br />
In this screenshot, you can see that the background is now brighter but the corners of the subwindows are still blue. These blue elements are images which provide the shadow of the subwindows. In the next step we will replace this image with a new one which fits our colors. Open the image for the left shadow which can be found here<br />
<br />
/themes/[YOUR_THEME_NAME]/img/border/cpbody-r.png<br />
<br />
Basicly, this image is only 4 pixel wide and infinite heigh. It doesn't matter if you cut it down to 1x4 pixel or make a 500x4 pixel version. It will be unlimited repeated. A easy way to add a shadow, is to use a gradient tool and make a 4 pixel gradient from a dark gray to a lighter gray.<br />
<br />
You also have to add a extra line to your global.css CSS file which looks like this.<br />
<br />
#ox-sidesplit {<br />
right: 1px !important;<br />
}<br />
<br />
Just add it to the bottom of your file.<br />
<br />
Take your new '''cpbody-r.png''' file and copy it into the same folder and overwrite the '''cpbody-l.png''' file. Then open it and rotate it for 180°. The left shadow is the same as the right one which means you can easily copy these files.<br />
<br />
Another quick CSS change is needed to fix some custom elements. Open <br />
<br />
/themes/[YOUR_THEME_NAME]/css/bgimages.css<br />
<br />
and change this line for the new created cpbody-l.png file.<br />
<br />
.cpheader-l {<br />
'''background-image: url("../img/border/cpbody-l.png");'''<br />
background-position: 0% 0%;<br />
background-repeat: repeat-y;<br />
}<br />
<br />
The last thing you have to do, is to change the panel-switcher or sometimes called panel toggler. It is the little arrow in the upper left corner if you have closed the folder panel. You have to change the background shadow, too. The file is located here:<br />
<br />
/themes/[YOUR_THEME_NAME]/img/border/spback.gif<br />
<br />
You also have to make a minor change in the '''bgimages.css''' file. Add the last line to this class which reduces the right position from -10 to -8.<br />
<br />
.sp-toggle<br />
{<br />
background-image:url(../img/border/spback.gif);<br />
'''right: -8px !important;'''<br />
}<br />
<br />
At this point, you are done with all shadows and borders and the background.<br />
<br />
== Panels and bars ==<br />
<br />
We start with the "module name bar" and the navigation panel. For this example, we change the background color with a image, a gradient image. Create a image you like and place it within your theme folder.<br />
<br />
/themes/[YOUR_THEME_NAME]/img/<br />
<br />
Now we have to add this image to our CSS files. Both bars or panels get their entries in the '''global.css'''. You can replace the existing entries with a new one. <br />
<br />
.topHeaderBG, .topheader-color {<br />
background-image: url("../img/background_g.png");<br />
}<br />
<br />
and<br />
<br />
div.oxTabControl {<br />
background-color: #dae1e6;<br />
background-image: url(../img/background_g.png);<br />
background-position: 100% 0;<br />
background-repeat: no-repeat;<br />
}<br />
<br />
You might need to change your font color for these bars in case you switched to a brighter background image or color. Both is set in the '''global.css'''<br />
<br />
.ox-sidepanel-title {<br />
color: black;<br />
}<br />
<br />
and<br />
<br />
div.oxTabControl td.oxTab:hover, div.oxTabControl td.oxTabLast:hover {<br />
background-color: #555;<br />
}<br />
<br />
You also might change the hover effect of the panel bar to fit the new colors:<br />
<br />
div.oxTabControl td.oxTab:hover, div.oxTabControl td.oxTabLast:hover {<br />
background-color: #ccc;<br />
}<br />
<br />
== Icons ==<br />
<br />
Since version 8.18.2 the Open-Xchange GUI comes with a new icon set. The old icons where a common 16x16 pixel GIF file. The new set comes in three different sizes, 16x16 pixel, 24x24 pixel and 34x34 pixel. Right now, only the 16x16 and 24x24 pixel icons are used. However, some of the new icons still exists as a old GIF file. If you take a closer look at the folder structure, you will see that all the new icons can be found at:<br />
<br />
/themes/[YOUR_THEME_NAME]/icons/<br />
<br />
The old icons can be found in the folder<br />
<br />
/themes/[YOUR_THEME_NAME]/img/<br />
<br />
With the help of '''Firebug''' you can easily get the correct path for the icon you want to change. For this example, we changed the top navigation icons for the Open-Xchange modules like mail, calendar, contacts aso.<br />
<br />
In the following screenshot, you can see the results after all changes we made so far which includes some new icons, a modified background and shadows and some new bars and panels.<br />
<br />
[[Image:Screen_step1.png|thumb|150px|none|Background]]<br />
<br />
<br />
== Branding, get your logo into the frontend ==<br />
<br />
The new version 6.18.2 comes without a branding icon or logo in the upper area like in version 6.18.1 and earlier versions. To get a logo back into the top area just follow this small tutorial.<br />
<br />
1. Go to your theme folder e.g. themes/${name}/css/<br />
<br />
2. Expand the file "concat.cssz" using gzip: "gzip -d -S .cssz concat.cssz"<br />
<br />
3. Open the file "concat" using a text editor (e.g. vim concat)<br />
<br />
4. Search for the tag '#branding'.<br />
Please note: Further details how-to enable the logo or how to change<br />
the height of the logo area, can be found in the comments.<br />
<br />
5. After editing the file, save your work and compress it again:<br />
"gzip -S .cssz concat" <br />
<br />
'''To test your modifications, clear your browser cache and hit the reload button of your browser.'''<br />
<br />
Please note:<br />
You will have to re-apply these changes on each update you install.<br />
<br />
== Branding, customize the headline area ==<br />
<br />
If you enabled the area with your logo on top of the page you may want to add additional html components like own buttons, links or additional images. <br />
This short how-to gives you an small example to add some text links and an additional image to this section.<br />
<br />
First create a new UI plugin like described in the article [[Gui Plugin Development|Gui_Plugin_Development]]. Open the register.js of your plugin and add this example code:<br />
<br />
//selects the branding div and append additional html elements using jQuery<br />
jQuery("#branding").append(<br />
jQuery("<div/>").css({ position: "absolute", right: "10px", lineHeight: "35px" }).append(<br />
jQuery("<div/>").css({ float: "right", color: "#449ccf", cursor: "pointer" }).text("Legal").click(function() { alert("Clicked on Legal") })<br />
).append(<br />
jQuery("<div/>").css({ float: "right", width: "30px", color: "#999999", textAlign: "center" }).text("|")<br />
).append(<br />
jQuery("<div/>").css({ float: "right", color: "#449ccf", cursor: "pointer" }).text("FAQs").click(function() { alert("Clicked on FAQs") })<br />
).append(<br />
jQuery("<div/>").css({ float: "right", width: "30px", color: "#999999", textAlign: "center" }).text("|")<br />
).append(<br />
jQuery("<div/>").css({ float: "right", color: "#449ccf", cursor: "pointer" }).text("Contact").click(function() { alert("Clicked on Contact") })<br />
)<br />
).append(<br />
jQuery("<div/>").css({ position: "absolute", height: "35px", width: "221px", left: "50%", marginLeft: "-110px", background: "url(" + ox.gui.themePath + "img/brand_middle.png)" })<br />
);<br />
<br />
[[Image:Example_logo_headline.png|thumb|600px|none|Example how it looks like]]<br />
<br />
<br />
As you can see you can use either use jQuery or the 'normal' document way to add DOM elements. Everything you need is some HTML and JavaScript knowlege.<br />
<br />
== The Login Page ==<br />
<br />
The very first page you see, called login page, contains only the logo, username and password fields and minor information about the current version. This page is part of the default theme which comes with the Open-Xchange groupware. If you want to customize this page, all changes will also be visible in the default theme for all other elements. This means, the default theme will always look like your login page.<br />
If you don't want to touch the default theme, a good way to handle this is to rename your default theme to something else, like '''ox_theme''' or '''old_theme''' and rename your new created theme to '''default'''. <br />
<br />
In the previous section '''Setup description''' we explained how to set up a new theme which was called '''mantis'''. When you change the default theme to something else just open the '''themes.properties''' file and change the entries there:<br />
<br />
modules/themes/default=Cool Water (Default)<br />
modules/themes/mantis=Mantis<br />
<br />
Change this file to something like this:<br />
<br />
modules/themes/default=Mantis<br />
modules/themes/old_ox=Cool Water<br />
<br />
Don't forget to change the folder names of your themes in your theme folder to the new names.<br />
<br />
rename /var/www/ox6/themes/default to /var/www/ox6/themes/old_ox<br />
rename /var/www/ox6/themes/mantis to /var/www/ox6/themes/default<br />
<br />
You can choose any name here. Important is the correct name in your '''themes.properties''' file which must be the same like the folder names. Otherwise, the client is not able to find them in your GUI folder.<br />
<br />
The final changes are quite simple. The upper logo bar is one big image which can be replaced with any other image. The shadows to the left, right and bottom are images, too. Open your '''bgimages.css''' CSS file and search for '''cpbody-l''', '''cpbody-r''', '''cpbottom-l''', '''cpbottom-r''' (the left and right shadows), '''cpbottom-b''' (the bottom shadow) and the two corners to the bottom left and right '''cpbottom-bl''' and '''cpbottom-br'''. If you remove the '''background-image''' in all of these classes, you will see a quick change. <br />
<br />
The overall '''background-color''' can be set in the '''global.css''' and effects the whole theme, too.<br />
<br />
body {<br />
'''background-color: #f1f1f1;'''<br />
font-family: Arial, Helvetica, sans-serif;<br />
font-size: 9pt;<br />
color:#000;<br />
}<br />
<br />
= Version 6.18.0 and lower =<br />
<br />
== Style ==<br />
<br />
Open the Open-Xchange CSS files for this changes.<br />
<br />
=== The Portal Page ===<br />
<br />
[[Image:Cut portal.jpg|thumb|150px|none|The Portal Page]]<br />
<br />
#<body> .background-color<br />
#cpbottom-color<br />
#font-color-disabled<br />
#font-style-headline<br />
#background-color-additional-content<br />
#border-background-default<br />
#font-color-default<br />
#font-style-lable<br />
#font-color-header<br />
#cpheader-color<br />
#font-style-headline<br />
#border-color-design<br />
#background-color-content<br />
#font-color-header<br />
#topHeaderBG<br />
<br />
<br />
=== The Calendar Page ===<br />
<br />
[[Image:Cut calendar.jpg|thumb|150px|none|The Calendar Page]]<br />
<br />
#font-color-disabled<br />
#wholeDayBackground<br />
#background-color-PMG-selection-elements<br />
#offTimeBackground<br />
#strokeCalendar<br />
#sectionStrokeCalendar<br />
#border-color-image<br />
#font-style-big-headline<br />
#kwSeperationBackGround<br />
#workTimeBackground<br />
<br />
<br />
=== Calendar Month View ===<br />
<br />
[[Image:Cut calendar month.jpg|thumb|150px|none|Calendar Month View]]<br />
<br />
#wholeDayBackground<br />
#appointmentTEMPORARY<br />
#appointmentRESERVED<br />
#appointmentABSENT<br />
#appointmentFREE<br />
#workTimeBackground<br />
#offTimeBackground<br />
<br />
<br />
=== New Appointment ===<br />
<br />
[[Image:Cut calendar new.jpg|thumb|150px|none|New Appointment]]<br />
<br />
#background-color-additional-content<br />
#font-color-disabled<br />
#border-color-design<br />
#border-color-content-default<br />
#background-color-content<br />
#font-style-lable<br />
#background-color-default<br />
<br />
<br />
=== New Appointment Series ===<br />
<br />
[[Image:Cut calendar new serie.jpg|thumb|150px|none|New Appointment Series]]<br />
<br />
#popupHeaderBackground<br />
#popup-header<br />
#greywrapper<br />
#background-color-additional-content<br />
#border-color-design<br />
#popupBackground<br />
<br />
=== Calendar Week View ===<br />
<br />
[[Image:Cut calendar week.jpg|thumb|150px|none|Calendar Week View]]<br />
<br />
#border-color-design<br />
#font-style-low<br />
<br />
<br />
=== Mail View ===<br />
<br />
[[Image:Cut mail.jpg|thumb|150px|none|Mail View]]<br />
<br />
#selected<br />
#tr<br />
#font-style-big-headline<br />
#font-style-lable<br />
#border-color-design<br />
#defaultContainer<br />
<br />
== Setup description ==<br />
<br />
After you have created and modified your theme, you should make those theme available in the configuration interface for users of the Open-Xchange Server. To do that, you only have to manifest your theme in the following server configuration file, afterwards your users can select your theme:<br />
<br />
/opt/open-xchange/etc/groupware/settings/themes.properties<br />
<br />
Each key in this property file must be prefixed with the theme bundle identifier. This is "com.openexchange.themes". The prefix must be followed with the unique identifier of a theme. This unique identifier specifies the directory name of the theme on the web server (/var/www/ox6/themes/ per default), too. The value of the property can be any name to described the theme. This name will be displayed in the AJAX GUI for selecting a theme. For example you should add the following line to this configuration file:<br />
<br />
com.openexchange.themes.[YOUR_THEME_NAME]=[YOUR_THEME_DESCRIPTION]<br />
<br />
Afterwards, restart the Open-Xchange service groupware. Your users can now select your theme.<br />
<br />
== End user view ==<br />
<br />
After you have created and configured your theme, your users will be able to select it in the configuration frontend:<br />
<br />
[[Image:Theme_selection.png]]<br />
<br />
[[Category: OX6]]<br />
<br />
= Icon Description =<br />
<br />
{| {{table}}<br />
| align="center" style="background:#f0f0f0;"|'''Icon'''<br />
| align="center" style="background:#f0f0f0;"|'''Name'''<br />
| align="center" style="background:#f0f0f0;"|'''Description'''<br />
|-<br />
| || || <br />
|-<br />
| ARROWS|| || <br />
|-<br />
| || || <br />
|-<br />
| ||arrow_darkgrey_left.gif||To change month, day, etc.<br />
|-<br />
| ||arrow_darkgrey_right.gif||To change month, day, etc.<br />
|-<br />
| ||arrow_double_gray_down.gif||All Modules; Panel; To open the Panel (right side)<br />
|-<br />
| ||arrow_double_gray_up.gif||All Modules; Panel; To close the Panel (right side)<br />
|-<br />
| ||arrow_double_gray_left.gif||<br />
|-<br />
| ||arrow_double_gray_right.gif||<br />
|-<br />
| ||arrow_double_white_left.gif||<br />
|-<br />
| ||arrow_gray_down.gif||Alle Modules; Panel; To open a Panel-Section<br />
|-<br />
| ||arrow_gray_right.gif|| <br />
|-<br />
| ||arrow-down.gif|| <br />
|-<br />
| ||sort_down.gif||All Modules; Views; To sort the entries<br />
|-<br />
| ||sort_up.gif||All Modules; Views; To sort the entries<br />
|-<br />
| || || <br />
|-<br />
| CALENDAR|| || <br />
|-<br />
| || || <br />
|-<br />
| ||btnnew_calendar.gif||Calendar-Module; Panel; To create a new appointment<br />
|-<br />
| ||calendar.gif||Sidebar; Foldertree; To mark calendar folder<br />
|-<br />
| ||calendar_series.gif||Calendar-Module; Appointments; To mark series<br />
|-<br />
| ||calendar16x16.gif||Calendar-Module; Appointments; To mark appointments<br />
|-<br />
| ||datepicker.gif||Calendar-Module; New Appointment-Dialog; To open a minicalendar<br />
|-<br />
| ||group.gif||Calendar-Module; Appointments; To mark group-appointments<br />
|-<br />
| ||mod_calendar_d.gif||Sidebar; Module-Overview; Calendar-Module is disabled<br />
|-<br />
| ||mod_calendar_sel.gif||Sidebar; Module-Overview; To jump into the calendar (Selected)<br />
|-<br />
| ||mod_calendar.gif||Sidebar; Module-Overview; To jump into the calendar<br />
|-<br />
| ||ressourcen.gif||Calendar-Module, Task-Module, E-Mail Module; Address book; To mark ressources<br />
|-<br />
| ||user_d.gif||Calendar-Module, Task-Module, Address book; To mark contact without E-Mail address<br />
|-<br />
| ||user_extern.gif||Calendar-Module, Task-Module, E-Mail Module; Address book; To mark none system user<br />
|-<br />
| ||user.gif||Calendar-Module, Task-Module, E-Mail Module; Address book; To mark system user<br />
|-<br />
| ||mod_calendar-1_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-1.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-2_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-2.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-3_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-3.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-4_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-4.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-5_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-5.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-6_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-6.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-7_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-7.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-8_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-8.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-9_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-9.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-10_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-10.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-11_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-11.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-12_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-12.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-13_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-13.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-14_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-14.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-15_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-15.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-16_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-16.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-17_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-17.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-18_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-18.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-19_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-19.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-20_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-20.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-21_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-21.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-22_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-22.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-23_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-23.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-24_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-24.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-25_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-25.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-26_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-26.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-27_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-27.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-28_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-28.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-29_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-29.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-30_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-30.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| ||mod_calendar-31_sel.gif||Sidebar; Module-Overview; Calendar-Module icon with current date (Selected)<br />
|-<br />
| ||mod_calendar-31.gif||Sidebar; Module-Overview; Calendar-Module icon with current date<br />
|-<br />
| || || <br />
|-<br />
| CONFIGURATION|| || <br />
|-<br />
| || || <br />
|-<br />
| ||configuration.gif|| <br />
|-<br />
| ||mod_configuration_d.gif||Sidebar; Module-Overview; Configuration is disabled<br />
|-<br />
| ||mod_configuration_sel.gif||Sidebar; Module-Overview; Configuration (Selected)<br />
|-<br />
| ||mod_configuration.gif||Sidebar; Module-Overview; Configuration<br />
|-<br />
| || || <br />
|-<br />
| CONTACTS|| || <br />
|-<br />
| || || <br />
|-<br />
| ||btnnew_contacts.gif||Contact-Module; Panel; To create a new contact<br />
|-<br />
| ||contacts.gif||Contact-Module; Contacts; To mark contacts<br />
|-<br />
| ||distributionlist34x34_n.gif||Distributionlist; Panel; To create a new distributionlist<br />
|-<br />
| ||dummypicture_add.gif||Contact-Module; New contact dialog/Detail view; To upload a new contact picture<br />
|-<br />
| ||dummypicture_small.gif||Contact-Module; New contact dialog/Detail view; To upload a new contact picture (Small)<br />
|-<br />
| ||dummypicture.gif||Contact-Module; New contact dialog/Detail view; To upload a new contact picture<br />
|-<br />
| ||mod_contacts_d.gif||Sidebar; Module-Overview; Contact is disabled<br />
|-<br />
| ||mod_contacts_sel.gif||Sidebar; Module-Overview; Contact is selected<br />
|-<br />
| ||mod_contacts.gif||Sidebar; Module-Overview; Contact<br />
|-<br />
| || || <br />
|-<br />
| FOLDER|| || <br />
|-<br />
| || || <br />
|-<br />
| ||calendar_dis.gif||Foldertree; Calendar-Folder; Disabled; No permissions<br />
|-<br />
| ||calendar.gif||Foldertree; Calendar-Folder<br />
|-<br />
| ||contacts_dis.gif||Foldertree; Contact-Folder; Disabled; No permissions<br />
|-<br />
| ||contacts.gif||Foldertree; Contact-Folder;<br />
|-<br />
| ||cutfolder_d.gif||Foldertree; RMB-Menue; Cut Folder; Disabled, No permissions<br />
|-<br />
| ||cutfolder.gif||Foldertree; RMB-Menue; Cut Folder;<br />
|-<br />
| ||document_locked.gif||InfoStore; Views; Document is locked<br />
|-<br />
| ||document.gif||InfoStore; Views; Document<br />
|-<br />
| ||draft_dis.gif||Foldertree; E-Mail; Draftsfolder; Disabled <br />
|-<br />
| ||draft.gif||Foldertree; E-Mail; Draftsfolder;<br />
|-<br />
| ||empty_folder_d.gif||Foldertree; RMB-Menue; Empty Folder; Disabled, No permissions<br />
|-<br />
| ||empty_folder.gif||Foldertree; RMB-Menue; Empty Folder;<br />
|-<br />
| ||facebook.png||<br />
|-<br />
| ||folder_closed_dis.gif||Foldertree; Folder-Icon; Closed; Disabled; No Permissions<br />
|-<br />
| ||folder_closed.gif||Foldertree; Folder-Icon; Closed;<br />
|-<br />
| ||folder_opened_dis.gif||Foldertree; Folder-Icon; Open; Disabled; No Permissions<br />
|-<br />
| ||folder_opened.gif||Foldertree; Folder-Icon; Open;<br />
|-<br />
| ||garbage_dis.gif||Foldertree; E-Mail; Trashfolder; Disabled<br />
|-<br />
| ||garbage.gif||Foldertree; E-Mail; Trashfolder;<br />
|-<br />
| ||globalsettings_dis.gif||Configuration; Options; Language & Region; Disabled<br />
|-<br />
| ||ham_dis.gif||Foldertree; E-Mail; Ham; Disabled<br />
|-<br />
| ||ham.gif||Foldertree; E-Mail; Ham;<br />
|-<br />
| ||inbox_dis.gif||Foldertree; E-Mail; Inbox; Disabled<br />
|-<br />
| ||inbox.gif||Foldertree; E-Mail; Inbox;<br />
|-<br />
| ||infostore_dis.gif||Foldertree; InfoStore; Disabled<br />
|-<br />
| ||infostore.gif||Foldertree; InfoStore;<br />
|-<br />
| ||mail_dis.gif||Foldertree; E-Mail; Root-Folder; Disabled<br />
|-<br />
| ||mail.gif||Foldertree; E-Mail; Root-Folder;<br />
|-<br />
| ||messaging_dis.gif||<br />
|-<br />
| ||messaging.gif||<br />
|-<br />
| ||mod_foldertree.gif||<br />
|-<br />
| ||myinfostore_dis.gif||Foldertree; InfoStore; Myinfostore Folder; Disabled<br />
|-<br />
| ||myinfostore.gif||Foldertree; InfoStore; Myinfostore Folder;<br />
|-<br />
| ||newfolder_d.gif||Foldertree; RMB-Menue; New Folder; Disabled, No permissions<br />
|-<br />
| ||newfolder.gif||Foldertree; RMB-Menue; New Folder;<br />
|-<br />
| ||outbox_dis.gif||Foldertree; E-Mail; Sent-Mail Folder; Disabled<br />
|-<br />
| ||outbox.gif||Foldertree; E-Mail; Sent-Mail Folder;<br />
|-<br />
| ||pastefolder_d.gif||Foldertree; RMB-Menue; Paste Folder; Disabled, No permissions<br />
|-<br />
| ||pastefolder.gif||Foldertree; RMB-Menue; Paste Folder;<br />
|-<br />
| ||propertiesfolder_d.gif||Foldertree; RMB-Menue; Properties; Disabled, No permissions<br />
|-<br />
| ||propertiesfolder.gif||Foldertree; RMB-Menue; Properties;<br />
|-<br />
| ||public_dis.gif||Foldertree; Public Folder; Disabled<br />
|-<br />
| ||public.gif||Foldertree; Public Folder;<br />
|-<br />
| ||renamefolder_d.gif||Foldertree; RMB-Menue; Rename Folder; Disabled, No permissions<br />
|-<br />
| ||renamefolder.gif||Foldertree; RMB-Menue; Rename Folder;<br />
|-<br />
| ||settings_folder_closed.gif||Configuration; Foldertree; Disabled<br />
|-<br />
| ||settings_folder_open.gif||Configuration; Foldertree;<br />
|-<br />
| ||settings.gif||Configuration; All pages and Headlines<br />
|-<br />
| ||shared.gif||Foldertree; Shared Folder<br />
|-<br />
| ||spam_dis.gif||Foldertree; E-Mail; Spam; Disabled<br />
|-<br />
| ||spam.gif||Foldertree; E-Mail; Spam;<br />
|-<br />
| ||tasks_dis.gif||Foldertree; Task; Root-Folder; Disabled<br />
|-<br />
| ||tasks.gif||Foldertree; Task; Root-Folder;<br />
|-<br />
| ||twitter.png||<br />
|-<br />
| ||user_dis.gif||Foldertree; UserStore; Disabled<br />
|-<br />
| ||user.gif||Foldertree; UserStore;<br />
|-<br />
| || || <br />
|-<br />
| HOVER|| || <br />
|-<br />
| || || <br />
|-<br />
| ||email_kl.gif||E-Mail; Hover; Displaying of E-Mails at the Hover<br />
|-<br />
| || || <br />
|-<br />
| INFOSTORE|| || <br />
|-<br />
| || || <br />
|-<br />
| ||btnnew_infostore.gif||InfoStore-Module; Panel; To create a new InfoStore-Object<br />
|-<br />
| ||infostore_save_d.gif||E-Mail; Panel or RMB; Save Attachment into the InfoStore; Disabled<br />
|-<br />
| ||infostore_save.gif||E-Mail; Panel or RMB; Save Attachment into the InfoStore;<br />
|-<br />
| ||infostore.gif||Foldertree; InfoStore;<br />
|-<br />
| ||mod_infostore_d.gif||Sidebar; Module-Overview; InfoStore is disabled<br />
|-<br />
| ||mod_infostore_sel.gif||Sidebar; Module-Overview; InfoStore is selected<br />
|-<br />
| ||mod_infostore.gif||Sidebar; Module-Overview; InfoStore<br />
|-<br />
| ||binary.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||ical.gif||<br />
|-<br />
| ||empty.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||image.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||java_jar.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||log.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||ooo_calc.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||ooo_draw.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||ooo_writer.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||pdf.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||postscript.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||tar.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||tgz.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||txt.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| ||vcard.gif||<br />
|-<br />
| ||video.png||InfoStore; Hover + Views; Mimetypes of Documents<br />
|-<br />
| || || <br />
|-<br />
| MAIL|| || <br />
|-<br />
| || || <br />
|-<br />
| ||mod_mail_d.gif||Sidebar; Module-Overview; E-Mail is disabled<br />
|-<br />
| ||mark_as.gif||E-Mail; Panel-Function; Mark Mail as<br />
|-<br />
| ||mark_as_d.gif||E-Mail; Panel-Function; Mark Mail as, Disabled<br />
|-<br />
| ||mail.gif||Foldertree; E-Mail; Root-Folder;<br />
|-<br />
| ||image_blocked.gif||E-Mail; Detail view of E-Mails; Blocked image for E-Mails with pictures<br />
|-<br />
| ||forward.gif||E-Mail; Panel-Function + RMB; Forward<br />
|-<br />
| ||forward_d.gif||E-Mail; Panel-Function + RMB; Forward, Disabled<br />
|-<br />
| ||email_priolow.gif||E-Mail; New E-Mail Dialog + E-Mail Views; Priorisation<br />
|-<br />
| ||email_priolhigh.gif||E-Mail; New E-Mail Dialog + E-Mail Views; Priorisation<br />
|-<br />
| ||email_priohigh.gif||E-Mail; New E-Mail Dialog + E-Mail Views; Priorisation<br />
|-<br />
| ||deleted.gif||E-Mail; Panel-Function + RMB; Delete E-Mail<br />
|-<br />
| ||mod_mail_sel.gif||Sidebar; Module-Overview; E-Mail is selected<br />
|-<br />
| ||mod_mail.gif||Sidebar; Module-Overview; E-Mail<br />
|-<br />
| ||noattachment.gif||<br />
|-<br />
| ||open_ISattachment_d.gif||E-Mail; Panel-Function + RMB; Open Attachment; Disabled<br />
|-<br />
| ||open_ISattachment.gif||E-Mail; Panel-Function + RMB; Open Attachment;<br />
|-<br />
| ||add_attachment_d.gif||E-Mail; Panel-Function; Add an Attachment; Disabled<br />
|-<br />
| ||add_attachment.gif||E-Mail; Panel-Function; Add an Attachment;<br />
|-<br />
| ||attachment.gif||E-Mail; Views; Attachment<br />
|-<br />
| ||btn_sendmail.gif||E-Mail; New E-Mail dialog; Panel; Send the E-Mail<br />
|-<br />
| ||btnnew_email.gif||E-Mail; Panel; New E-Mail<br />
|-<br />
| ||read.gif||E-Mail; Views; E-Mail is read<br />
|-<br />
| ||remove_attachment_d.gif||E-Mail; Panel-Function + RMB; Delete an Attachment; Disabled<br />
|-<br />
| ||remove_attachment.gif||E-Mail; Panel-Function + RMB; Delete an Attachment;<br />
|-<br />
| ||reply_all_d.gif||E-Mail; Panel-Function + RMB + Views; Reply all; Disabled<br />
|-<br />
| ||reply_all.gif||E-Mail; Panel-Function + RMB + Views; Reply all;<br />
|-<br />
| ||reply_d.gif||E-Mail; Panel-Function + RMB + Views; Reply; Disabled<br />
|-<br />
| ||reply_forward.gif||E-Mail; Views; Replyed and Forwarded<br />
|-<br />
| ||reply.gif||E-Mail; Panel-Function + RMB + Views; Reply<br />
|-<br />
| ||spam_d.gif||E-Mail; Panel-Function + RMB; Mark as Spam; Disabled<br />
|-<br />
| ||spam.gif||E-Mail; Panel-Function + RMB; Mark as Spam;<br />
|-<br />
| ||unread.gif||E-Mail; Views; Unread<br />
|-<br />
| ||write_mail_d.gif||E-Mail; New E-Mail Dialog; Save as Draft, Disabled<br />
|-<br />
| ||write_mail.gif||E-Mail; New E-Mail Dialog; Save as Draft,<br />
|-<br />
| || || <br />
|-<br />
| MENU|| || <br />
|-<br />
| || || <br />
|-<br />
| ||add_appointment_d.gif||Contact; New Contact Dialog; Add a birthday appointment; Disabled<br />
|-<br />
| ||add_appointment.gif||Contact; New Contact Dialog; Add a birthday appointment;<br />
|-<br />
| ||add_category_d.gif||Configuration; Tags; Panel; Add Category; Disabled<br />
|-<br />
| ||add_category.gif||Configuration; Tags; Panel; Add Category;<br />
|-<br />
| ||add_extview_d.gif||Configuration; Startpage; UWA-Widgets; Panel; Add Widget; Disabled<br />
|-<br />
| ||add_extview.gif||Configuration; Startpage; UWA-Widgets; Panel; Add Widget;<br />
|-<br />
| ||add_member_participant_d.gif||Calendar; New Appointment Dialog; Participant Tabulator; Panel; Add new participant; Disabled<br />
|-<br />
| ||add_member_participant.gif||Calendar; New Appointment Dialog; Participant Tabulator; Panel; Add new participant;<br />
|-<br />
| ||add_picture_d.gif||Contact; New Contact Dialog; Panel; Add new picture; Disabled<br />
|-<br />
| ||add_picture.gif||Contact; New Contact Dialog; Panel; Add new picture;<br />
|-<br />
| ||add_signature_d.gif||Configuration; E-Mail; Signatures; Panel; Add new Signature; Disabled<br />
|-<br />
| ||add_signature.gif||Configuration; E-Mail; Signatures; Panel; Add new Signature;<br />
|-<br />
| ||adress1_d.gif||Contact, Views; Route; Disabled<br />
|-<br />
| ||adress1_n.gif||Contact, Views; Route;<br />
|-<br />
| ||alsanlagesenden_d.gif||InfoStore; Panel; Send as Attachment; Disabled<br />
|-<br />
| ||alsanlagesenden.gif||InfoStore; Panel; Send as Attachment;<br />
|-<br />
| ||attachment_open_d.gif||All Modules; Panel + RMB; Open Attachment; Disabled<br />
|-<br />
| ||attachment_open.gif||All Modules; Panel + RMB; Open Attachment;<br />
|-<br />
| ||attachment_save_d.gif||All Modules; Panel + RMB; Save Attachment; Disabled<br />
|-<br />
| ||attachment_save.gif||All Modules; Panel + RMB; Save Attachment;<br />
|-<br />
| ||btn_save.gif||Configuration; Panel; Save changes<br />
|-<br />
| ||calendar_move_d.gif||Calendar; Panel; Move selected appointment; Disabled<br />
|-<br />
| ||calendar_move.gif||Calendar; Panel; Move selected appointment;<br />
|-<br />
| ||cancel_clear_d.gif||All Modules; Panel; Search; Clear entries; Disabled<br />
|-<br />
| ||cancel_clear.gif||All Modules; Panel; Search; Clear entries;<br />
|-<br />
| ||close_linking.gif||<br />
|-<br />
| ||contact_copy_d.gif||Contact; Panel; Copy selected Contact; Disabled<br />
|-<br />
| ||contact_copy.gif||Contact; Panel; Copy selected Contact;<br />
|-<br />
| ||contact_move_d.gif||Contact; Panel; Move selected Contact; Disabled<br />
|-<br />
| ||contact_move.gif||Contact; Panel; Move selected Contact;<br />
|-<br />
| ||copy_mail_d.gif||E-Mail; Panel; Copy selected Mail; Disabled<br />
|-<br />
| ||copy_mail.gif||E-Mail; Panel; Copy selected Mail;<br />
|-<br />
| ||delete_d.gif||All Modules; Panel; Delete; Disabled<br />
|-<br />
| ||delete_folder_d.gif||Foldertree; RMB-Menue; Delete Folder; Disabled, No permissions<br />
|-<br />
| ||delete_folder.gif||Foldertree; RMB-Menue; Delete Folder;<br />
|-<br />
| ||delete.gif||All Modules; Panel; Delete;<br />
|-<br />
| ||distributionlist_d.gif||<br />
|-<br />
| ||distributionlist_extcont_d.gif||Distributionlist; Create new List; Panel; Add external Contact; Disabled<br />
|-<br />
| ||distributionlist_extcontact_d.gif||<br />
|-<br />
| ||distributionlist_extcontact.gif||Distributionlist; Create new List; Panel; Add external Contact;<br />
|-<br />
| ||distributionlist_intcont_d.gif||Distributionlist; Create new List; Panel; Add internal Contact; Disabled<br />
|-<br />
| ||distributionlist_intcontact.gif||Distributionlist; Create new List; Panel; Add internal Contact;<br />
|-<br />
| ||distributionlist_remove_d.gif||Distributionlist; Create new List; Panel; Remove Contact; Disabled<br />
|-<br />
| ||distributionlist_remove.gif||Distributionlist; Create new List; Panel; Remove Contact;<br />
|-<br />
| ||distributionlist.gif||Distributionlist; Create new Icon + Views<br />
|-<br />
| ||duplicate_contacts_d.gif||Contact; Panel; Duplicate selected Contact; Disabled<br />
|-<br />
| ||duplicate_contacts.gif||Contact; Panel; Duplicate selected Contact;<br />
|-<br />
| ||edit_d.gif||All Modules; Panel; Edit selected Object; Disabled<br />
|-<br />
| ||edit_draft_d.gif||<br />
|-<br />
| ||edit_draft.gif||E-Mail; Drafts-Folder; Edit selected Draft Mail<br />
|-<br />
| ||edit.gif||Configuration; E-Mail; Signatures; Edit selected Signature<br />
|-<br />
| ||entsperren_d.gif||InfoStore; Panel + RMB; Unlock Object; Disabled<br />
|-<br />
| ||entsperren.gif||InfoStore; Panel + RMB; Unlock Object;<br />
|-<br />
| ||externalview_activate_d.gif||Configuration; Startpage; UWA-Module; Panel; Activate UWA; Disabled<br />
|-<br />
| ||externalview_activate_n.gif||Configuration; Startpage; UWA-Module; Panel; Activate UWA;<br />
|-<br />
| ||externalview_deactivate_d.gif||Configuration; Startpage; UWA-Module; Panel; Deactivate UWA; Disabled<br />
|-<br />
| ||externalview_deactivate_n.gif||Configuration; Startpage; UWA-Module; Panel; Deactivate UWA;<br />
|-<br />
| ||externalview_edit_d.gif||Configuration; Startpage; UWA-Module; Panel; Edit UWA; Disabled<br />
|-<br />
| ||externalview_edit_n.gif||Configuration; Startpage; UWA-Module; Panel; Edit UWA;<br />
|-<br />
| ||global_conf_change_d.gif||Calendar + Task; Panel + RMB + Hover; Change confirmation status; Disabled<br />
|-<br />
| ||global_confirmation_change_d.gif||<br />
|-<br />
| ||global_confirmation_change.gif||Calendar + Task; Panel + RMB + Hover; Change confirmation status;<br />
|-<br />
| ||ham_d.gif||<br />
|-<br />
| ||ham.gif||<br />
|-<br />
| ||img_import.gif||Configuration; Import; Panel; Import function<br />
|-<br />
| ||infostorecurrentversion_d.gif||<br />
|-<br />
| ||infostorecurrentversion.gif||<br />
|-<br />
| ||mail_move_d.gif||E-Mail; Panel; Move selected Mail; Disabled<br />
|-<br />
| ||mail_move.gif||E-Mail; Panel; Move selected Mail;<br />
|-<br />
| ||move_folder_d.gif||Foldertree; RMB-Menue; Move Folder; Disabled, No permissions<br />
|-<br />
| ||move_folder.gif||Foldertree; RMB-Menue; Move Folder;<br />
|-<br />
| ||move_infostoreobject_d.gif||InfoStore; Panel; Move selected Object; Disabled<br />
|-<br />
| ||move_infostoreobject.gif||InfoStore; Panel; Move selected Object;<br />
|-<br />
| ||print_d.gif||All Modules; Panel; Print selected Object; Disabled<br />
|-<br />
| ||print.gif||All Modules; Panel; Print selected Object;<br />
|-<br />
| ||remove_category_d.gif||Configuration; Tags; Panel; Remove Tag; Disabled<br />
|-<br />
| ||remove_category.gif||Configuration; Tags; Panel; Remove Tag;<br />
|-<br />
| ||remove_extview_d.gif||Configuration; Startpage; UWA-Module; Panel; Remove UWA; Disabled<br />
|-<br />
| ||remove_extview.gif||Configuration; Startpage; UWA-Module; Panel; Remove UWA;<br />
|-<br />
| ||remove_picture_d.gif||Contact; Views; Panel; Remove contact picture; Disabled<br />
|-<br />
| ||remove_picture.gif||Contact; Views; Panel; Remove contact picture;<br />
|-<br />
| ||remove_signature_d.gif||Configuration; E-Mail; Signature; Panel; Remove Signature; Disabled<br />
|-<br />
| ||remove_signature.gif||Configuration; E-Mail; Signature; Panel; Remove Signature;<br />
|-<br />
| ||remove_tag_d.gif||All Modules; Panel; Flag; Remove Flag; Disabled<br />
|-<br />
| ||remove_tag.gif||All Modules; Panel; Flag; Remove Flag;<br />
|-<br />
| ||remove_teammember_d.gif||Configuration; Calendar; Teams; Panel; Remove Teammember; Disabled<br />
|-<br />
| ||remove_teammember.gif||Configuration; Calendar; Teams; Panel; Remove Teammember;<br />
|-<br />
| ||remove_userrights_d.gif||Foldertree; RMB; Properties; Rights-Tabulator; Panel; Remove User; Disabled<br />
|-<br />
| ||remove_userrights.gif||Foldertree; RMB; Properties; Rights-Tabulator; Panel; Remove User;<br />
|-<br />
| ||save_as_link_d.gif||<br />
|-<br />
| ||save_as_link.gif||<br />
|-<br />
| ||search-rightpadding_d.gif||<br />
|-<br />
| ||search-rightpadding.gif||All Modules; Panel; Search Section; Start Search<br />
|-<br />
| ||section_scroll_left_d.gif||<br />
|-<br />
| ||section_scroll_left_dis.gif||<br />
|-<br />
| ||section_scroll_left.gif||<br />
|-<br />
| ||section_scroll_right_d.gif||<br />
|-<br />
| ||section_scroll_right_dis.gif||<br />
|-<br />
| ||section_scroll_right.gif||<br />
|-<br />
| ||sperren_d.gif||InfoStore; Panel + RMB; Lock Object; Disabled<br />
|-<br />
| ||sperren.gif||InfoStore; Panel + RMB; Lock Object;<br />
|-<br />
| ||tag_0.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_1.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_2.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_3.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_4.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_5.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_6.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_7.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_8.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_9.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_10.gif||All Modules; Panel + Views; Flag-Section;<br />
|-<br />
| ||tag_d.gif||All Modules; Panel + Views; Flag-Section; Disabled<br />
|-<br />
| ||task_copy_d.gif||Task; Panel + RMB; Use as Template; Disabled<br />
|-<br />
| ||task_copy.gif||Task; Panel + RMB; Use as Template;<br />
|-<br />
| ||task_move_d.gif||Task; Panel; Move; Disabled<br />
|-<br />
| ||task_move.gif||Task; Panel; Move;<br />
|-<br />
| ||teamchange_d.gif||Calendar; Panel; Team view; Choos Team; Disabled<br />
|-<br />
| ||teamchange.gif||Calendar; Panel; Team view; Choos Team;<br />
|-<br />
| ||userrights_d.gif||Foldertree; RMB; Properties; Rights-Tabulator; Panel; Disabled<br />
|-<br />
| ||userrights.gif||Foldertree; RMB; Properties; Rights-Tabulator; Panel;<br />
|-<br />
| ||view_emailsource_d.gif||E-Mail; Panel + RMB; View E-Mail Source, Disabled<br />
|-<br />
| ||view_emailsource.gif||E-Mail; Panel + RMB; View E-Mail Source,<br />
|-<br />
| ||weiterzuListe.gif||Calendar; All Views; Jump to the list view<br />
|-<br />
| || || <br />
|-<br />
| PORTAL|| || <br />
|-<br />
| || || <br />
|-<br />
| ||big_portal.png||<br />
|-<br />
| ||btn_close.gif||Portal; Widgets; Close Widgets<br />
|-<br />
| ||mod_portal_d.gif||Sidebar; Module-Overview; Portal is disabled<br />
|-<br />
| ||mod_portal_sel.gif||Sidebar; Module-Overview; Portal is selected<br />
|-<br />
| ||mod_portal.gif||Sidebar; Module-Overview; Portal is<br />
|-<br />
| ||move_n.gif|| <br />
|-<br />
| || || <br />
|-<br />
| SMILIES|| || <br />
|-<br />
| || || <br />
|-<br />
| ||big_smile.gif||E-Mail; Smilies<br />
|-<br />
| ||cool.gif||E-Mail; Smilies<br />
|-<br />
| ||hmm.gif||E-Mail; Smilies<br />
|-<br />
| ||neutral.gif||E-Mail; Smilies<br />
|-<br />
| ||sad.gif||E-Mail; Smilies<br />
|-<br />
| ||smile.gif||E-Mail; Smilies<br />
|-<br />
| ||wink.gif||E-Mail; Smilies<br />
|-<br />
| || || <br />
|-<br />
| TABS|| || <br />
|-<br />
| || || <br />
|-<br />
| ||free_busy_icon.gif||Calendar; New Appointment; Tab Free/Busy<br />
|-<br />
| ||history_n.gif||<br />
|-<br />
| || || <br />
|-<br />
| TASKS|| || <br />
|-<br />
| || || <br />
|-<br />
| ||btnnew_task.gif||Task; Panel; New Task<br />
|-<br />
| ||mod_tasks_d.gif||Sidebar; Module-Overview; Tasks is disabled<br />
|-<br />
| ||mod_tasks_sel.gif||Sidebar; Module-Overview; Tasks is selected<br />
|-<br />
| ||mod_tasks.gif||Sidebar; Module-Overview; Tasks<br />
|-<br />
| ||sequence.gif||Task-Module; Task; To mark series<br />
|-<br />
| ||taskprio1.gif||Task; New Task; Priorization<br />
|-<br />
| ||taskprio2.gif||Task; New Task; Priorization<br />
|-<br />
| ||taskprio3.gif||Task; New Task; Priorization<br />
|-<br />
| ||tasks.gif||Task-Module; Task; To mark tasks<br />
|-<br />
| ||tasks16x16.gif||Foldertree; Task<br />
|-<br />
| || || <br />
|-<br />
| TOOLBAR|| || <br />
|-<br />
| || || <br />
|-<br />
| ||calnder.png||Sidebar; Minicalendar; To jump in the monthview<br />
|-<br />
| ||configuration.gif||Toolbar; Configuration (NEW)<br />
|-<br />
| ||help.gif||Toolbar; Help (NEW)<br />
|-<br />
| ||ox_animated.gif||<br />
|-<br />
| ||ox_logo.gif||<br />
|-<br />
| ||smallwait.gif||<br />
|-<br />
| ||tb_loading.gif||Toolbar; Reload (NEW)<br />
|-<br />
| || || <br />
|-<br />
| FURTHER ICONS|| || <br />
|-<br />
| || || <br />
|-<br />
| ||bg_disabled.gif||<br />
|-<br />
| ||browsercheck.gif||<br />
|-<br />
| ||dnd_disabled.gif||All Modules; Drag&Drop of Objects isn’t possible<br />
|-<br />
| ||dnd.gif||All Modules; Drag&Drop of Objects is possible<br />
|-<br />
| ||grip_bg_horizontal.gif||<br />
|-<br />
| ||grip_bg_vertical.gif||<br />
|-<br />
| ||minus.gif||Foldertree; To close the subfolders<br />
|-<br />
| ||new_na.png||<br />
|-<br />
| ||new.png||Configuration; Panel; Create new Setting (Mailfilter)<br />
|-<br />
| ||noplus.gif||<br />
|-<br />
| ||ox_animated_black.gif||<br />
|-<br />
| ||ox_animated_default.gif||<br />
|-<br />
| ||ox_animated_white.gif||<br />
|-<br />
| ||ox_animated_withoutbg.gif||<br />
|-<br />
| ||pg_bg.png||<br />
|-<br />
| ||pg_green.png||<br />
|-<br />
| ||pg_orange.png||<br />
|-<br />
| ||pg_red.png||<br />
|-<br />
| ||plus.gif||Foldertree; To open the subfolders<br />
|-<br />
| ||private_flag.gif||All Modules; New Dialogs; Set Objects to private<br />
|-<br />
| ||quota.png||<br />
|-<br />
| ||split_bg_h.gif||<br />
|-<br />
| ||split_bg_v.gif||<br />
|-<br />
| ||split_grip_h.gif||<br />
|-<br />
| ||split_grip_v.gif||<br />
|-<br />
| ||x.png||Confirmation Dialogs; Close this dialogs<br />
|-<br />
| ||||<br />
|-<br />
| ICONS 16x16||||<br />
|-<br />
| ||||<br />
|-<br />
| ||attachment_add.png||Add Attachments<br />
|-<br />
| ||attachment_open.png||Open Attachments<br />
|-<br />
| ||attachment_remove.png||Remove Attachments<br />
|-<br />
| ||calendar_dis.png||Disabled calendar folder icon<br />
|-<br />
| ||calendar_move.png||Move appointments icon<br />
|-<br />
| ||calendar.png||A calendar folder icon<br />
|-<br />
| ||confirmation_change.png||Change confirmation of an appointment<br />
|-<br />
| ||contact_copy.png||Copy of a contact<br />
|-<br />
| ||contact_move.png||Move a contact<br />
|-<br />
| ||contacts_dis.png||Disabled contact folder icon<br />
|-<br />
| ||contacts.png||Folder icon for contact folder<br />
|-<br />
| ||current_version.png||Open current version of this infostore document<br />
|-<br />
| ||delete_folder.png||Delete a folder<br />
|-<br />
| ||delete.png||Delete icon (sometimes used as close window)<br />
|-<br />
| ||distributionlist_extcontact.png||Add external contact or email to a distributionlist<br />
|-<br />
| ||draft_dis.png||Disabled draft folder icon<br />
|-<br />
| ||draft.png||Draft folder icon<br />
|-<br />
| ||dummy.gif||A empty icon, sometimes used as placeholder<br />
|-<br />
| ||duplicate_contacts.png||Duplicate a contact<br />
|-<br />
| ||facebook.png||The facebook folder icon<br />
|-<br />
| ||folder_closed_dis.png||Disabled version of a closed folder icon<br />
|-<br />
| ||folder_closed.png||A closed folder icon<br />
|-<br />
| ||folder_opened_dis.png||Disabled version of a opened folder icon<br />
|-<br />
| ||folder_opened.png||A opened folder icon<br />
|-<br />
| ||forward.png||Forward a mail<br />
|-<br />
| ||garbage_dis.png||Disabled garbage folder icon<br />
|-<br />
| ||garbage.png||Garbage folder icon<br />
|-<br />
| ||ham_dis.png||Disabled ham (opposite to spam) folder icon<br />
|-<br />
| ||ham.png||A ham folder icon<br />
|-<br />
| ||inbox_dis.png||Disabled mail Inbox folder icon<br />
|-<br />
| ||inbox.png||Mail Inbox folder icon<br />
|-<br />
| ||infostore_dis.png||Disabled Infostore folder icon<br />
|-<br />
| ||infostore_move.png||Move a infostore element icon<br />
|-<br />
| ||infostore.png||A infostore folder icon<br />
|-<br />
| ||lock.png||A closed lock icon (used to lock/unlock infostore items)<br />
|-<br />
| ||mail_copy.png||Copy a mail<br />
|-<br />
| ||mail_dis.png||Disabled mail folder icon<br />
|-<br />
| ||mail_move.png||Move a mail<br />
|-<br />
| ||mail.png||Mail folder icon<br />
|-<br />
| ||mail_source.png||View mail sourcecode<br />
|-<br />
| ||mark_as.png||Mark mail as read/unread<br />
|-<br />
| ||member_add.png||Add a member to an appointment<br />
|-<br />
| ||member_remove.png||Remove a member from an appointment<br />
|-<br />
| ||mod_calendar.png||The calendar module icon<br />
|-<br />
| ||mod_configuration.png||The configuration module icon<br />
|-<br />
| ||mod_contacts.png||The contact module icon<br />
|-<br />
| ||mod_infostore.png||The infostore module icon<br />
|-<br />
| ||mod_mail.png||The mail module icon<br />
|-<br />
| ||mod_portal.png||The portal module icon<br />
|-<br />
| ||mod_tasks.png||The task module icon<br />
|-<br />
| ||outbox_dis.png||Disabled outbox folder icon<br />
|-<br />
| ||outbox.png||Outbox folder icon<br />
|-<br />
| ||print.png||A print icon<br />
|-<br />
| ||public_dis.png||Disabled public folder icon<br />
|-<br />
| ||public.png||A public folder icon<br />
|-<br />
| ||rss.png||RSS folder icon<br />
|-<br />
| ||save.png||A save icon<br />
|-<br />
| ||search.png||A search icon<br />
|-<br />
| ||send_as_attachment.png||Send this infostore item as a mail attachment<br />
|-<br />
| ||send_as_link.png||Send this infostore item as a link to the infostore<br />
|-<br />
| ||shared_dis.png||Disabled shared folder icon<br />
|-<br />
| ||shared_globe.png||A additional shared icon which will be overlaid on other folder icons if they are public or shared<br />
|-<br />
| ||shared.png||A shared folder icon<br />
|-<br />
| ||spam_dis.png||Disabled spam folder icon<br />
|-<br />
| ||spam.png||A spam folder icon<br />
|-<br />
| ||task_copy.png||Copy a task entry<br />
|-<br />
| ||task_move.png||Move a task entry<br />
|-<br />
| ||tasks_dis.png||Disabled task folder icon<br />
|-<br />
| ||tasks.png||A task folder icon<br />
|-<br />
| ||teamchange.png||Calendar teamview icon<br />
|-<br />
| ||twitter.png||The twitter folder icon<br />
|-<br />
| ||unlock.png||A unlock icon (used to lock/unlock infostore items)<br />
|-<br />
| ||user_dis.png||Disabled user icon (used in appointments and contacts)<br />
|-<br />
| ||user.png||A user icon<br />
|-<br />
| ||userrights_delete.png||The delete rights of a folder<br />
|-<br />
| ||userrights.png||Add a user to the rights of a folder<br />
|-<br />
| ||userrights_read.png||The read rights of a folder<br />
|-<br />
| ||userrights_remove.png||Remove a user from the rights of a folder<br />
|-<br />
| ||userrights_write.png||The write/modify rights of a folder<br />
|}</div>Thomas.siedentopfhttps://oxpedia.org/wiki/index.php?title=Template:AddReposSLES&diff=9085Template:AddReposSLES2011-10-04T14:58:08Z<p>Thomas.siedentopf: typo</p>
<hr />
<div>= Add Open-Xchange Repository =<br />
<br />
Open-Xchange maintains public available software repositories for different platforms, such as SLES. This repository should be added to the SLES installation to enable simple installation and updates.<br />
<br />
Start a console and add the Open-Xchange software repository for {{{slesname}}}:<br />
<br />
$ zypper {{{zyparg}}} http://software.open-xchange.com/OX6/stable/{{{slesname}}}/ ox <br />
<br />
<br />
If you have a valid maintenance subscription, please run the following command so that the most recent packages get installed:<br />
<br />
$ zypper {{{zyparg}}} http://LDBACCOUNT:LDBPASSWORD@software.open-xchange.com/OX6/updates/{{{slesname}}} oxupdates<br />
<br />
A warning will be shown because the Open-Xchange packages are not yet signed by a cryptographic key. To accept and continue the installation, press Y.</div>Thomas.siedentopf