https://oxpedia.org/wiki/api.php?action=feedcontributions&user=Steffen.templin&feedformat=atomOpen-Xchange - User contributions [en]2024-03-28T23:18:44ZUser contributionsMediaWiki 1.31.0https://oxpedia.org/wiki/index.php?title=AppSuite:ImageConverter_Install&diff=24354AppSuite:ImageConverter Install2018-10-26T13:10:51Z<p>Steffen.templin: </p>
<hr />
<div>= Download & Installation Imageconverter =<br />
<br />
=== General Information ===<br />
<br />
OX App Suite displays images (photos and graphics) in many different ways as<br />
<br />
* Thumbnails<br />
* Icons<br />
* Images embedded in documents <br />
* in Emails<br />
* in an own pop-up window.<br />
<br />
The image processing is done by the OX middleware and not by a dedicated service, so that the middleware might consume a lot of cpu time just to convert images to different target formats. Furthermore the OX middleware does not cache images for a longer time. Only thumbnails get cached, either by the database or file system based. These images get converted into the required formats (e.g. jpeg, png) when requested by an user action in the user Interface.<br />
<br />
With OX App Suite 7.10 there is an alternative to process images by the OX middleware. The image conversion and delivery can be delegated to an extra service, the OX ImageConverter server. It's deployment model is exactly corresponding to the documentconverter server via a client/server service.<br />
<br />
The separation of the ImageConverter service has the following advantages:<br />
<br />
Configuration and usage of one or more separate storages<br />
Performance improvements via persistent cache<br />
Pre-rendering of pre-defined formats and sizes (defaults are auto:200x150, auto:480x320, auto:640x480, auto:800x600, auto:1280x720, auto:1920x1080") if resolution of the source image allows this.<br />
Best matching size will be delivered without new conversion, if an image is requested by the Middleware<br />
Browser is able to cache those images<br />
No limits for image sizes<br />
The default target format is specified by configured, predefined formats. By using the 'auto' (beside 'jpg' or 'png') target format, opaque source images are converted to JPEG target images and transparent images are converted to PNG target images.<br />
Reduce load of OX Middleware<br />
<br />
== Requirements ==<br />
<br />
See the [[AppSuite:OX_System_Requirements|Open-Xchange software requirements page]] for details.<br />
<br />
== Mandatory Modules ==<br />
<br />
Additional functional modules need to be installed separately on the user servicing OX App Suite middleware nodes:<br />
<br />
* The Image Converter Client: See [[AppSuite:ImageConverterClientInstall|Image converter client installation instructions]]<br />
<br />
== Installation ==<br />
<br />
The Image Converter deployment consists of the package <tt>open-xchange-imageconverter-server</tt>.<br />
<br />
=== Redhat Enterprise Linux 6 or CentOS 6 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Redhat Enterprise Linux 7, CentOS 7 or Amazon Linux 2 ===<br />
<br />
Add the following repositories to your Open-Xchange yum configuration:<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ yum install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 8.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== Debian GNU/Linux 9.0 ===<br />
<br />
Add the following repositories to your Open-Xchange apt configuration:<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianStretch|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-imageconverter-server<br />
<br />
=== SUSE Linux Enterprise Server 12 === <br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|imageconverter}}<br />
<br />
if you have a valid maintenance subscription, please add also following repositories by replacing the credentials.<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|imageconverter/updates}}<br />
<br />
$ zypper ref<br />
$ zypper install open-xchange-imageconverter-server<br />
<br />
== Monitoring ==<br />
<br />
Image Converter offers runtime information via JMX about the Image Converter. This [[AppSuite:ImageConverterMonitoring|article]] guides to the information how to access JMX data, configure and use Jolokia and integrate with munin.<br />
<br />
== Configuration ==<br />
<br />
The following property files need to be adjusted on the ImageConverter node to ensure correct runtime behavior of the ImageConverter implementation<br />
<br />
* fileitem.properties<br />
* imageconverter.properties<br />
<br />
=== Filestores ===<br />
<br />
Since the ImageConverter service uses the FileItemService, which itself needs a dedicated filestore and a dedicated database schema, the following steps need to be performed by the admin prior to starting the ImageConverter WebService.<br />
<br />
'''Please note:''' Currently only file-system based filestores (NFS) are supported, object storage support is subject to a later release.<br />
<br />
Create a directory for the FileItemService filestore(s) with OS commands, that is writable for the user, running the OX backends:<br />
<br />
$ mkdir -p /var/opt/fileitemstore<br />
$ chown open-xchange:open-xchange /var/opt/fileitemstore<br />
<br />
Register the FileItemService filestore(s) via the OX admin command registerfilestore after installation. Since the the RMI port for administrative calls to the ImageConverter server is set to 1095 by default, this port has to be set within the environment, prior to making the registerfilestore call itself. If making the administration call on the system by using an already running middleware server, the port setting can be omitted.<br />
<br />
Since the ImageConverter filestore is a dedicated filestore for this service only, the number of allowed contexts for the filestore must be set to 0 (by using switch '-x 0') in order to prevent the middleware from using this filestore as an additional filestorage.<br />
<br />
$ env RMI_HOSTNAME=rmi://localhost:1095 /opt/open-xchange/sbin/registerfilestore -A oxadminmaster -P ${AS_ADMINMASTER_PASS} -x 0 -t file:///var/opt/fileitemstore<br />
<br />
Enter the id(s) of the FileItemService filestore(s) (put into the configdb database by using the registerfilestore command) into the fileitem.properties configuration file<br />
<br />
Create a new, empty database schema to be used by the FileItemService: <br />
<br />
$ /opt/open-xchange/imageconverter/sbin/initfileitemdb -i --fileitemdb-pass="${AS_DB_PASS}" --fileitemdb-user=openexchange --fileitemdb-host=localhost --fileitemdb-port=3306 --fileitemdb-dbname=fileitemdb<br />
<br />
Enter the database connection data, used to initialize the FileItemService database in the previous 'initfileitemdb' call into the appropriate fields of the fileitem.properties configuration file. Please take care to enter the 'read' properties as well as the 'write' properties within the configuration file.<br />
<br />
The following properties of the fileitem.properties need to be adjusted, at least (example values are provided):<br />
<br />
$ com.openexchange.fileItem.fileStoreIds=3<br />
$<br />
$ com.openexchange.fileItem.readUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.readProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.readProperty.2=password=${AS_DB_PASS}<br />
$<br />
$ com.openexchange.fileItem.writeUrl=jdbc:mysql://localhost/fileitemdb<br />
$ com.openexchange.fileItem.writeProperty.1=user=openexchange<br />
$ com.openexchange.fileItem.writeProperty.2=password=${AS_DB_PASS}<br />
<br />
The ImageConverter itself currently relies on the external ImageMagick framework, so that this package has to be installed on the node, the ImageConverter is running on<br />
<br />
=== ImageMagick ===<br />
<br />
On Amazon Linux 2, ImageMagick is located under ''/bin''. Therefore the property ''com.openexchange.imageconverter.imagemagick.searchPath'' must be adjusted accordingly.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=Template:ContextUserAndLogs&diff=24308Template:ContextUserAndLogs2018-10-12T10:59:41Z<p>Steffen.templin: </p>
<hr />
<div><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 [[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 [[Csv_import|page]].<br />
<br />
= Log files and issue tracking =<br />
== Default logging mechanism ==<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 />
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 />
* [[AppSuite:OX_Logging|Logback configuration Guide OX App Suite]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=My.cnf&diff=24307My.cnf2018-10-12T10:38:12Z<p>Steffen.templin: </p>
<hr />
<div>== Introduction ==<br />
<br />
This page lists some performance tuning parameters which we recommend for tuning MySQL database services used for Open-Xchange installations.<br />
<br />
We cannot guarantee this is an exhaustive list of required settings. So treat this list of tunings as probably required, but not necessarily sufficient settings for optimal MySQL performance.<br />
<br />
Furthermore, as MySQL changes over time, settings which have been correct as of the time of writing may become incorrect later.<br />
<br />
However, this list of settings is the result of internal performance testing and real world customer feedback, so it should be valid to some extent.<br />
<br />
In the end, proper configuration of the database service for performance, but also consistency, durability and high availability is in the responsibility of the customer.<br />
<br />
=== Performance items ===<br />
<br />
* You should adjust the <code>innodb_buffer_pool_size</code> parameter for reasonable memory usage. Our DB sizing is mainly memory-driven and this is where most of the memory goes. Our standard DB machine sizing assumption is 32 GB if MySQL dedicated memory on a 48 GB total memory machine. On such a machine, you would configure 32 GB for the innodb_buffer_pool size, being aware that MySQL does also require memory for other things, in particular there are some also per-connection related memory spendings, which can become substantial if you allow for a lot of maximum concurrent connections. Please watch your memory configuration carefully, use monitoring and tools like mysqltuner.pl.<br />
<br />
* On bigger installations you should use <code>innodb_file_per_table = 1</code>, which is creating single files instead of one big blob. If you change this parameter after the database initialization you have to recreate (like dump/drop and re-import) the tables.<br />
<br />
* It can help to put different parts of the mysql datadir (iblog, ibdata) on different filesystems / storage devices. This depends on your infrastructure. Settings herefore are <code>datadir</code>, <code>innodb_data_home_dir</code>, <code>innodb_log_group_home_dir</code>.<br />
<br />
* If your storage is fast (handle a lot of IOPS), you may want to adjust the <code>innodb_io_capacity</code> setting, which defines a limit for the IOPS MySQL will create. The default is 200, which is sensible for single spindle disks. But if you have storage appliances with a lot of fast SAS drives, or even SSDs, this limit can be increased greatly.<br />
<br />
=== Functional items ===<br />
<br />
* Query cache is to be switched off; as we found in our own benchmarks and as backed up by upstreams, this hurts performance in load situations with high concurrency. [https://dev.mysql.com/doc/refman/5.7/en/query-cache.htm The query cache is deprecated as of MySQL 5.7.20, and is removed in MySQL 8.0], so we recommend also to switch that off.<br />
* Starting with App Suite 7.10.0, <code>character_set_server</code> must be set to <code>utf8mb4</code> and <code>collation_server</code> to <code>utf8mb4_general_ci</code>. For older versions it must be <code>utf8</code> and <code>utf8_general_ci</code> respectively.<br />
* Starting with MySQL 5.7 <code>innodb_strict_mode</code> must be disabled.<br />
* Starting with MySQL 5.7 and MariaDB 10.2 <code>sql_mode</code> must be configured according to belows matrix.<br />
<br />
==== SQL mode matrix ====<br />
<br />
The default for the <code>sql_mode</code> setting changes regularly with MariaDB and MySQL releases and is not even consistent anymore between the two derivates. SQL modes affect how data and queries are handled at runtime. Enabling strict modes might lead to errors in terms of failing queries or even update tasks. We strongly recommend the following configuration to avoid according runtime errors:<br />
<br />
{| class="wikitable"<br />
|-<br />
! scope="col"| sql_mode<br />
! scope="col"| App Suite 7.8.4<br />
! scope="col"| App Suite 7.10.0<br />
|-<br />
! scope="row"| MySQL 5.6<br />
| <code>NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_ENGINE_SUBSTITUTION</code><br />
|-<br />
! scope="row"| MySQL 5.7<br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION,ONLY_FULL_GROUP_BY</code><br />
|-<br />
! scope="row"| MariaDB 10.1<br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
|-<br />
! scope="row"| MariaDB 10.2<br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
|-<br />
|}<br />
<br />
=== Sample config files ===<br />
<br />
For easy deployment we recommend not to edit existing the existing my.cnf file, rather assume the distro provides sane settings for most of the items and override items where needed.<br />
<br />
As in MySQL there is a [https://dev.mysql.com/doc/refman/5.7/en/option-files.html last instance wins] semantic in options file parsing, we propose to create a custom include directory "ox.conf.d", put our custom config files therein, and include this directory as latest directory in /etc/mysql/my.cnf.<br />
<br />
To put in that directory, we have one main tuning file called tunings.cnf, one galera-related file if galera is in use, and one more galera host-specific file which contains per-host settings if using galera (separate in a file of its own for easier configuration management).<br />
<br />
So, start with adding to the existing my.cnf at the very bottom:<br />
<br />
!includedir /etc/mysql/ox.conf.d/<br />
<br />
Create that directory and put in there the generic ox tunings file /etc/mysql/ox.conf.d/tunings.cnf:<br />
<br />
[mysqld]<br />
bind-address = *<br />
<br />
#innodb_use_native_aio = 0<br />
<br />
table_open_cache = 3072<br />
table_definition_cache = 4096<br />
max_heap_table_size = 64M<br />
tmp_table_size = 64M<br />
max_connections = 505<br />
max_user_connections = 500<br />
max_allowed_packet = 16M<br />
thread_cache_size = 32<br />
query_cache_size = 0<br />
query_cache_type = 0<br />
innodb_buffer_pool_size = 32G<br />
# the default value in MySQL 5.6.6 and higher is 8 when innodb_buffer_pool_size is greater than or equal to 1GB. Otherwise, the default is 1. <br />
innodb_buffer_pool_instances = 32<br />
innodb_data_file_path = ibdata1:128M:autoextend<br />
innodb_file_per_table = 1<br />
# innodb_log_file_size should be 25% of the innodb_buffer_pool_size<br />
innodb_log_file_size = 4GB<br />
# default and recommended value is 2<br />
innodb_log_files_in_group = 2<br />
# adjust according to your storage<br />
#innodb_io_capacity = 1000<br />
<br />
# we are unsure about this setting. Newer versions of MariaDB seem to be fine with low (=1) settings for this value.<br />
# Traditionally we encountered values up to 4x the number of cores.<br />
# Default seems to be number of cores, so let's stick the default<br />
# In the end, we need to leave this setting up to you: if you dont get full cpu utilization in cpu-bound situations, this might be a setting to increase.<br />
#thread_pool_size = 32<br />
<br />
binlog_cache_size = 1M<br />
sync_binlog = 8<br />
binlog_format = row<br />
<br />
character_set_server = utf8mb4<br />
collation_server = utf8mb4_general_ci<br />
<br />
# This was default_table_type previous to MySQL 5.5<br />
default_storage_engine = InnoDB<br />
<br />
innodb_autoinc_lock_mode = 2<br />
<br />
# keep until 5.6, deprecated later<br />
innodb_locks_unsafe_for_binlog = 1<br />
<br />
# we found this has huge impact on (galera) performance<br />
# default (consistent) setting of 1 greatly severs performance<br />
# in galera (or async master-slave) deployments, you might be ok with setting this to 0 or 2,<br />
# assuming our consistency / availability comes from replication / other cluster nodes<br />
innodb_flush_log_at_trx_commit = 0<br />
<br />
# for performance testing systems, to not use excessive disk space<br />
#expire_logs_days = 1<br />
<br />
# MySQL 5.7.7 has changed the default to 1. Disable it explicitly to prevent from errors based on invalid data stored by former App Suite or MySQL versions.<br />
innodb_strict_mode = 0<br />
<br />
# The following value refers to App Suite 7.10 on top of MySQL 5.7. For other combinations see the sql mode matrix at http://oxpedia.org/wiki/index.php?title=My.cnf.<br />
sql_mode = NO_ENGINE_SUBSTITUTION,NO_AUTO_CREATE_USER,ONLY_FULL_GROUP_BY<br />
<br />
If using galera, use the following galera configuration file <code>/etc/mysql/ox.conf.d/wsrep.cnf</code>. See the comments in that file for values to be adjusted.<br />
<br />
[mysqld]<br />
# adjust for your distros SO location<br />
wsrep_provider=/usr/lib/libgalera_smm.so<br />
<br />
# this is the big winner and enables us to switch off OX's replication monitor<br />
wsrep_sync_wait=1<br />
<br />
# pick a unique cluster name<br />
wsrep_cluster_name=devcluster<br />
# adjust for your IPs / hostnames<br />
wsrep_cluster_address=gcomm://10.20.29.68,10.20.29.69,10.20.29.70<br />
<br />
# put this in host.cnf<br />
#wsrep_node_name=...<br />
#wsrep_node_address=...<br />
<br />
# For some MariaDB versions, xtrabackup-v2 no longer works, instead use "mariabackup"<br />
# (needs to be installed separately, e.g. via the mariadb-backup-10.2 package)<br />
# see upstream documentation for details: <br />
# https://mariadb.com/kb/en/library/getting-started-with-mariadb-galera-cluster/#xtrabackup<br />
#<br />
# wsrep_sst_method=mariabackup<br />
wsrep_sst_method=xtrabackup-v2<br />
<br />
# wsrep_sst_auth if of format username:password<br />
# pick whatever you configured on the donor node<br />
wsrep_sst_auth=sstuser:...<br />
<br />
# galera-specific tunings<br />
wsrep_slave_threads = 32<br />
<br />
# finally, enable wsrep: required for some MariaDB versions<br />
wsrep_on=ON -- Enable wsrep replication (MariaDB starting 10.1.1) <br />
<br />
Galera-related host-specific settings go in /etc/mysql/ox.conf.d/host.cnf:<br />
<br />
[mysqld]<br />
# the nodes hostname<br />
wsrep_node_name=...<br />
# and the IP of the wsrep relevant interface, if multiple<br />
wsrep_node_address=10.20.29.68</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Installation_Guide_for_Debian_8.0&diff=24227AppSuite:Open-Xchange Installation Guide for Debian 8.02018-08-21T13:15:55Z<p>Steffen.templin: /* Requirements */</p>
<hr />
<div>{{Version|7.8.4, 7.10.x}}<br />
<br />
= OX App Suite on Debian GNU/Linux 8.0 =<br />
<br />
{{QuickInstIntro|release=appsuite}}<br />
<br />
= Requirements =<br />
<br />
* Plain installed Debian GNU/Linux 8.0, no graphical tools required<br />
* A supported Java Virtual Machine ([http://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Java 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 <code>apt-get install vim</code> first.<br />
<br />
= Debian Jessie backports repository for OpenJDK 8 (only for AppSuite 7.10.0) =<br />
<br />
OX App Suite v7.10.0 requires OpenJDK 8 while for previous OX App Suite versions Java version 7 was required. Unfortunately Debian Jessie does not contain Java version 8. Therefore we need to install it from the Debian Jessie backports repositories to be able to run OX App Suite v7.10.0 on Debian Jessie.<br />
<br />
Add the repository for Debian Jessie backports.<br />
<br />
$ cat <<EOF > /etc/apt/sources.list.d/backports.list<br />
deb http://<your debian mirror>/debian jessie-backports main<br />
EOF<br />
<br />
Furthermore you need to allow the Debian package manager to install the OpenJDK 8 related packages from the Debian Jessie backports repository. Normally these packages have less priority and are not chosen as installation candidates. Raise the priority as shown below:<br />
<br />
$ cat <<EOF > /etc/apt/preferences.d/ca-certificates-java.pref<br />
Package: ca-certificates-java<br />
Pin: release a=jessie-backports<br />
Pin-Priority: 501<br />
EOF<br />
<br />
Now the package manager is able to choose OpenJDK 8 from the Debian Jessie backports.<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 />
{{AddReposDebian|debname=jessie|debnameox=DebianJessie|release=appsuite}}<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 />
{{OXPackageInstallation|installer=apt-get|javavendor=sun|release=appsuite}}<br />
<br />
{{OXConfiguration}}<br />
<br />
{{oxinstaller|connector=http}}<br />
<br />
After initializing the configuration, restart the Open-Xchange Administration service by executing:<br />
<br />
$ systemctl restart open-xchange<br />
<br />
{{OXRegister|globaldb=true}}<br />
<br />
= Configure services =<br />
<br />
{{ApacheOXModsDebian|connector=http|extramods=lbmethod_byrequests}}<br />
<br />
{{Template:ApacheAppSuiteConf|connector=http|connectorConf=/etc/apache2/conf-available/proxy_http.conf|apacheconf=/etc/apache2/sites-enabled/000-default.conf|docroot=/var/www/html|loadmodule=|syncProxyName=eas_oxcluster}}<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 />
== Upgrade from Debian 7 ==<br />
<br />
If you updated from Debian 7 to Debian 8 the proxy_http.conf file is still located in the <tt>conf.d</tt> directory which is not read in Debian 8. So you have to move the file to <tt>conf-available</tt> and execute <tt>a2enconf proxy_http</tt> afterwards.<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 />
[[Tune_apache2_for_more_concurrent_connections|Apache Setting for more concurrent Connections]]<br />
<br />
{{ContextUserAndLogs}}<br />
<br />
[[Category: AppSuite]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:7_10_Database_Migration&diff=24059AppSuite:7 10 Database Migration2018-06-21T12:01:32Z<p>Steffen.templin: Apply input from Dominik</p>
<hr />
<div>{{Version|7.10.0}}<br />
<br />
= Database Migration with OX App Suite v7.10.0 =<br />
<br />
OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read this paper carefully to ensure a smooth and clean upgrade process.<br />
<br />
== Change Overview ==<br />
<br />
The most significant changes are:<br />
* New version and configuration requirements.<br />
* Most VARCHAR columns need to migrated to utf8mb4 character encoding.<br />
* A major rewrite of the calendar application requires full data migration.<br />
<br />
We strongly recommend to thoroughly plan and test the upgrade procedure. To gain insights about update task runtimes and the expected load, our recommendation is to clone ConfigDB and the biggest UserDB and perform an isolated test upgrade that especially covers the calendar migration and character encoding changes. Update task durations can be significantly longer than with previous upgrades and the migrations might cause noticeable higher I/O load. Also some additional disk space is needed during and after the migrations.<br />
<br />
== Database System ==<br />
<br />
MySQL Server is supported in versions 5.6 and 5.7 with recent patch levels only and MariaDB Server 10.1 and 10.2 respectively. Support for 5.6/10.1 exists for compatibility reasons and is transitional. We recommend upgrading to 5.7/10.2 as soon as possible. Any database system upgrade must happen before App Suite is upgraded to OX App Suite v7.10.0. Please follow the respective guides of your database vendor carefully.<br />
<br />
Different App Suite and database system versions require different configurations of the DBMS, please follow http://oxpedia.org/wiki/index.php?title=My.cnf to have your database configured in a sane way. Especially the following items require some attention with the upgrade to App Suite 7.10.0 and upgrades of the DBMS itself:<br />
<br />
* Supported SQL modes are only <code>NO_ENGINE_SUBSTITUTION</code> and <code>NO_AUTO_CREATE_USER</code>. Starting with App Suite 7.10.0, <code>ONLY_FULL_GROUP_BY</code> is also supported for MySQL 5.7. It is still not with older versions of MySQL or any MariaDB version! To review the current value, use <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'sql_mode';</code>.<br />
* Ensure that <code>character_set_server</code> is set to <code>utf8</code> for App Suite 7.8.x. Again the current global default value can be obtained via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'character_set_server';</code>. With 7.10.0 being fully rolled out, this setting must then be changed to <code>utf8mb4</code>. If <code>collation_server</code> is configured explicitly, it must be set to a matching value according to the character set in either case!<br />
<br />
Note that App Suite <= 7.8.4 did not support MySQL 5.7/MariaDB 10.2 so far. While we recommend it for 7.10.0, this leaves a lack of definition during the upgrade process. We consider running 7.8.4 on top of MySQL 5.7/MariaDB 10.2 a valid scenario as long as it is transitional during the upgrade phase. Please take our configuration recommendations seriously to mitigate potential user-facing issues as far as possible.<br />
<br />
== Upgrade Procedure ==<br />
<br />
The upgrade to OX App Suite v7.10.0 can be performed like any other major upgrade before. However, the duration of blocking database update tasks for the mentioned charset and calendar migrations could conflict with customers’ availability demands. Therefore it is possible to decouple these special time- and resource-intensive tasks from the plain version upgrade. In this section a multi-step approach is described that performs the version upgrade before and independently from the migrations. Every step always results in a working system that is ready to serve user traffic. Some functional implications that affect user experience are outlined in the according subsections.<br />
<br />
'''Important:''' Even though the first step leads to a basically working OX App Suite v7.10.0 environment, the subsequent steps are not optional but mandatory! Skipping the migrations will leave a few calendar features dysfunctional and can lead to issues with certain SQL queries that use explicit collations for searching and sorting. Running OX App Suite v7.10.0 in production without having all parts of the migration fulfilled is not supported – OX support will request you to complete the migration tasks when reporting issues that are not related to the migration itself. <br />
<br />
== Initial OX App Suite v7.10.0 Rollout ==<br />
If not done so far, upgrade your MySQL installation to a version supported with OX App Suite v7.10.0 but configure it to be compatible with OX App Suite v7.8.x as described in the “Database System” section.<br />
<br />
Despite the fact that the two special migrations for calendar and character sets are explicitly skipped, this section assumes that the “Rolling Upgrade with breaking Hazelcast upgrade” is applied as described in http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster. For the application server upgrade, the common guide from http://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages can be followed.<br />
<br />
Prepare a dedicated App Suite middleware node that will be used to perform the database update tasks. The node must not be serving any user traffic and be prepared with<br />
<br />
* OX App Suite v7.10.0 packages<br />
* Configuration according to the user production nodes<br />
* The Hazelcast rolling upgrade compatibility package (see http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Rolling_Upgrade_with_breaking_Hazelcast_upgrade)<br />
* Exclude the update tasks for both mentioned migrations (i.e. calendar and character encoding). See “Update Task Exclusion” for details.<br />
* Execute update tasks according to your preferred strategy. More on this can be found at http://oxpedia.org/wiki/index.php?title=UpdateTasks.<br />
<br />
Update tasks operate on database schemas sequentially, one at a time. All users from all contexts of a given schema are logged out and locked out. Then, DB schema changes are executed. Finally, users are unlocked and able to login again. Schemas typically contain a few thousand users (if our recommended sizing is being followed) and thus executing update tasks means bunches of a few thousand users will be affected sequentially. You will not have a full downtime. For each update task execution process the following statements hold true:<br />
<br />
* All users got service for nearly all the time (all the time but the time where their schema is upgraded)<br />
* For each point in time, nearly all users got service (all but the ones from the currently updated schema)<br />
* When update tasks are completed, all users will have been affected by one "logout" - "locked out" cycle<br />
<br />
After complete and successful update task execution, roll out OX App Suite v7.10.0 to one node after another. After complete rollout, reconfigure MySQL if appropriate as described in the “Database System” section.<br />
<br />
=== Update Task Exclusion ===<br />
<br />
Add the following lines to <code>/opt/open-xchange/etc/excludedupdatetasks.properties</code> or remove the leading # character if already included, so that it contains these two lines:<br />
<br />
# Character Encoding Migration<br />
com.openexchange.groupware.update.excludedUpdateTasks=groupware.utf8mb4<br />
<br />
# Calendar Migration<br />
com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask<br />
<br />
The first line does not denote one dedicated update task, but a whole list of tasks. To make exclusion more convenient, the concept of update task namespaces has been introduced. All update tasks belonging to the character encoding migration are part of the <code>groupware.utf8mb4</code> namespace. The denoted property takes care of excluding them all at once. You can list all according tasks with the <code>/opt/open-xchange/sbin/listUpdateTaskNamespaces</code> tool.<br />
<br />
== Character Encoding Migration ==<br />
<br />
The default character encoding for Unicode (named character set by MySQL) of MySQL will become <code>utf8mb4</code> in the near future. MariaDB on Debian Stretch (9) already has an according default configuration set when installing it from distribution packages. So far all VARCHAR columns are supposed to store at max. 3-byte UTF-8 characters due to the nature of MySQL’s utf8 character encoding. This leads to the fact that for example emojis cannot be saved as part of any App Suite entities. In a mixed-mode scenario (App Suite considers MySQL to operate in utf8mb4 mode due to the <code>character_set_server</code> setting, while columns are specified with utf8 encoding), this leads to issues whenever certain collations during SELECT statements are enforced. To avoid such issues generally and also increase user experience by finally allowing characters from the Unicode astral plane, Open-Xchange has decided to migrate existing data structures to the utf8mb4 character encoding.<br />
<br />
This migration can be executed before or after the calendar migration, while it is recommend to execute it before.<br />
<br />
The upgrade procedure is basically the same as above in terms executing update tasks, while the server software is already up to date and needs no further upgrades:<br />
<br />
* Again prepare one dedicated node that doesn’t serve any user traffic<br />
* Remove the according namespace property from <code>excludedupdatetasks.properties</code> again, but still keep the “ChronosStorageMigrationTask”. Afterwards restart the open-xchange daemon.<br />
* Execute update tasks according to your preferred strategy.<br />
<br />
'''Important:''' The update tasks require a lot of tables to be copied and re-created, leading to high I/O and especially sequential read and write operations. For every copied table the needed MySQL disk space doubles during the update task, so ensure enough free space before running the migration.<br />
<br />
== Calendar Data Migration ==<br />
<br />
The new calendar stack in OX App Suite v7.10.0 comes along with a new data model using its very own tables in MySQL. To preserve users calendar data, an update task <code>com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask</code> has been introduced, that reads all data from the old tables, applies transformations to match the new stack and writes it into the new tables. The approach and upgrade process is described in detail at https://documentation.open-xchange.com/7.10.0/middleware/components/calendar/data_migration.html. Please read that article carefully before continuing. Especially we want to emphasize again the recommendation to test the migration with a copy of your real data to exclude or determine any issues beforehand.<br />
<br />
Before executing this update task, OX App Suite v7.10.0 uses the new calendar stack on top of the old database tables through a compatibility layer. As the old storage layout lacks certain functionality, not all features are functional in between the application upgrade and execution of the update task. Due to this fact, a few spots are affected where not all appointment data that the user interface allows to enter can be persisted. This includes:<br />
<br />
* Reminders, where still only one notification prior the appointment start is possible<br />
* Colors, that cannot be mapped to the previously used labels<br />
* 4-byte UTF-8 characters (emojis) are not yet possible<br />
* Secret appointments, that are still stored as private ones<br />
* An appointment's end timezone can't be applied, if it's different from the start timezone<br />
<br />
Operators of ''non-Galera'' MySQL setups - i.e. Master-Slave replication - can potentially speed up the migration by configuring <code>com.openexchange.calendar.migration.intermediateCommits = false</code>. Per default the migration is performed in batches that separately committed, as Galera does not cope well with large transactions. By changing the setting to <code>false</code>, a single transaction with batch-mode enabled is used.<br />
<br />
'''Important:''' The migrating of calendar data actually leads to a duplication of that data. Also with OX App Suite v7.10.0 every new calendar data is written to both, the old and the new tables redundantly to preserve to ability to roll back to OX App Suite v7.8.4. However, only the parts can preserved that match the old data model. I.e. additional features like multiple reminders or subscriptions of external calendars (Google Calendar, SchedJoules) cannot be preserved during a rollback.<br />
<br />
A repeated OX App Suite v7.10.0 upgrade after a former rollback to OX App Suite v7.8.4 requires to force re-execution of this update task!</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:7_10_Database_Migration&diff=24058AppSuite:7 10 Database Migration2018-06-21T11:50:05Z<p>Steffen.templin: /* Database System */</p>
<hr />
<div>{{Version|7.10.0}}<br />
<br />
= Database Migration with OX App Suite v7.10.0 =<br />
<br />
OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read this paper carefully to ensure a smooth and clean upgrade process.<br />
<br />
== Change Overview ==<br />
<br />
The most significant changes are:<br />
* New version and configuration requirements.<br />
* Most VARCHAR columns need to migrated to utf8mb4 character encoding.<br />
* A major rewrite of the calendar application requires full data migration.<br />
<br />
We strongly recommend to thoroughly plan and test the upgrade procedure. To gain insights about update task runtimes and the expected load, our recommendation is to clone ConfigDB and the biggest UserDB and perform an isolated test upgrade that especially covers the calendar migration and character encoding changes. Update task durations can be significantly longer than with previous upgrades and the migrations might cause noticeable higher I/O load. Also some additional disk space is needed during and after the migrations.<br />
<br />
== Database System ==<br />
<br />
MySQL Server is supported in versions 5.6 and 5.7 with recent patch levels only and MariaDB Server 10.1 and 10.2 respectively. Support for 5.6/10.1 exists for compatibility reasons and is transitional. We recommend upgrading to 5.7/10.2 as soon as possible. Any database system upgrade must happen before App Suite is upgraded to OX App Suite v7.10.0. Please follow the respective guides of your database vendor carefully.<br />
<br />
Different App Suite and database system versions require different configurations of the DBMS, please follow http://oxpedia.org/wiki/index.php?title=My.cnf to have your database configured in a sane way. Especially the following items require some attention with the upgrade to App Suite 7.10.0 and upgrades of the DBMS itself:<br />
<br />
* Supported SQL modes are only <code>NO_ENGINE_SUBSTITUTION</code> and <code>NO_AUTO_CREATE_USER</code>. Starting with App Suite 7.10.0, <code>ONLY_FULL_GROUP_BY</code> is also supported for MySQL 5.7. It is still not with older versions of MySQL or any MariaDB version! To review the current value, use <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'sql_mode';</code>.<br />
* Ensure that <code>character_set_server</code> is set to <code>utf8</code> for App Suite 7.8.x. Again the current global default value can be obtained via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'character_set_server';</code>. With 7.10.0 being fully rolled out, this setting must then be changed to <code>utf8mb4</code>. If <code>collation_server</code> is configured explicitly, it must be set to a matching value according to the character set in either case!<br />
<br />
== Upgrade Procedure ==<br />
<br />
The upgrade to OX App Suite v7.10.0 can be performed like any other major upgrade before. However, the duration of blocking database update tasks for the mentioned charset and calendar migrations could conflict with customers’ availability demands. Therefore it is possible to decouple these special time- and resource-intensive tasks from the plain version upgrade. In this section a multi-step approach is described that performs the version upgrade before and independently from the migrations. Every step always results in a working system that is ready to serve user traffic. Some functional implications that affect user experience are outlined in the according subsections.<br />
<br />
'''Important:''' Even though the first step leads to a basically working OX App Suite v7.10.0 environment, the subsequent steps are not optional but mandatory! Running OX App Suite v7.10.0 in production without having all parts of the migration fulfilled is not supported – OX support will request you to complete the migration tasks when reporting issues that are not related to the migration itself.<br />
<br />
== Initial OX App Suite v7.10.0 Rollout ==<br />
If needed and not done so far, upgrade your MySQL installation to a version supported with OX App Suite v7.10.0 but configure it to be compatible with OX App Suite v7.8.x as described in the “Database System” section.<br />
<br />
Despite the fact that the two special migrations for calendar and character sets are explicitly skipped, this section assumes that the “Rolling Upgrade with breaking Hazelcast upgrade” is applied as described in http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster. For the application server upgrade, the common guide from http://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages can be followed.<br />
<br />
Prepare a dedicated App Suite middleware node that will be used to perform the database update tasks. The node must not be serving any user traffic and be prepared with<br />
<br />
* OX App Suite v7.10.0 packages<br />
* Configuration according to the user production nodes<br />
* The Hazelcast rolling upgrade compatibility package (see http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Rolling_Upgrade_with_breaking_Hazelcast_upgrade)<br />
* Exclude the update tasks for both mentioned migrations. See “Update Task Exclusion” for details.<br />
* Execute update tasks according to your preferred strategy. More on this can be found at http://oxpedia.org/wiki/index.php?title=UpdateTasks.<br />
<br />
After complete and successful update task execution, roll out OX App Suite v7.10.0 to one node after another. After complete rollout, reconfigure MySQL if appropriate as described in the “Database System” section.<br />
<br />
=== Update Task Exclusion ===<br />
<br />
Add the following lines to <code>/opt/open-xchange/etc/excludedupdatetasks.properties</code> or remove the leading # character if already included, so that it contains these two lines:<br />
<br />
# Character Encoding Migration<br />
com.openexchange.groupware.update.excludedUpdateTasks=groupware.utf8mb4<br />
<br />
# Calendar Migration<br />
com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask<br />
<br />
The first line does not denote one dedicated update task, but a whole list of tasks. To make exclusion more convenient, the concept of update task namespaces has been introduced. All update tasks belonging to the character encoding migration are part of the <code>groupware.utf8mb4</code> namespace. The denoted property takes care of excluding them all at once. You can list all according tasks with the <code>/opt/open-xchange/sbin/listUpdateTaskNamespaces</code> tool.<br />
<br />
== Character Encoding Migration ==<br />
<br />
The default character encoding for Unicode (named character set by MySQL) of MySQL will become <code>utf8mb4</code> in the near future. MariaDB on Debian Stretch (9) already has an according default configuration set when installing it from distribution packages. So far all VARCHAR columns are supposed to store at max. 3-byte UTF-8 characters due to the nature of MySQL’s utf8 character encoding. This leads to the fact that for example emojis cannot be saved as part of any App Suite entities. In a mixed-mode scenario (App Suite considers MySQL to operate in utf8mb4 mode due to the <code>character_set_server</code> setting, while columns are specified with utf8 encoding), this leads to issues whenever certain collations during SELECT statements are enforced. To avoid such issues generally and also increase user experience by finally allowing characters from the Unicode astral plane, Open-Xchange has decided to migrate existing data structures to the utf8mb4 character encoding.<br />
<br />
This migration can be executed before or after the calendar migration, while it is recommend to execute it before.<br />
<br />
The upgrade procedure is basically the same as above in terms executing update tasks, while the server software is already up to date and needs no further upgrades:<br />
<br />
* Again prepare one dedicated node that doesn’t serve any user traffic<br />
* Remove the according namespace property from <code>excludedupdatetasks.properties</code> again, but still keep the “ChronosStorageMigrationTask”. Afterwards restart the open-xchange daemon.<br />
* Execute update tasks according to your preferred strategy.<br />
<br />
'''Important:''' The update tasks require a lot of tables to be copied and re-created, leading to high I/O and especially sequential read and write operations. For every copied table the needed MySQL disk space doubles during the update task, so ensure enough free space before running the migration.<br />
<br />
== Calendar Data Migration ==<br />
<br />
The new calendar stack in OX App Suite v7.10.0 comes along with a new data model using its very own tables in MySQL. To preserve users calendar data, an update task <code>com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask</code> has been introduced, that reads all data from the old tables, applies transformations to match the new stack and writes it into the new tables. The approach and upgrade process is described in detail at https://documentation.open-xchange.com/7.10.0/middleware/components/calendar/data_migration.html. Please read that article carefully before continuing. Especially we want to emphasize again the recommendation to test the migration with a copy of your real data to exclude or determine any issues beforehand.<br />
<br />
Before executing this update task, OX App Suite v7.10.0 uses the new calendar stack on top of the old database tables through a compatibility layer. As the old storage layout lacks certain functionality, not all features are functional in between the application upgrade and execution of the update task. Due to this fact, a few spots are affected where not all appointment data that the user interface allows to enter can be persisted. This includes:<br />
<br />
* Reminders, where still only one notification prior the appointment start is possible<br />
* Colors, that cannot be mapped to the previously used labels<br />
* 4-byte UTF-8 characters (emojis) are not yet possible<br />
* Secret appointments, that are still stored as private ones<br />
* An appointment's end timezone can't be applied, if it's different from the start timezone<br />
<br />
Operators of ''non-Galera'' MySQL setups - i.e. Master-Slave replication - can potentially speed up the migration by configuring <code>com.openexchange.calendar.migration.intermediateCommits = false</code>. Per default the migration is performed in batches that separately committed, as Galera does not cope well with large transactions. By changing the setting to <code>false</code>, a single transaction with batch-mode enabled is used.<br />
<br />
'''Important:''' The migrating of calendar data actually leads to a duplication of that data. Also with OX App Suite v7.10.0 every new calendar data is written to both, the old and the new tables redundantly to preserve to ability to roll back to OX App Suite v7.8.4. However, only the parts can preserved that match the old data model. I.e. additional features like multiple reminders or subscriptions of external calendars (Google Calendar, SchedJoules) cannot be preserved during a rollback.<br />
<br />
A repeated OX App Suite v7.10.0 upgrade after a former rollback to OX App Suite v7.8.4 requires to force re-execution of this update task!</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:7_10_Database_Migration&diff=24057AppSuite:7 10 Database Migration2018-06-21T10:07:21Z<p>Steffen.templin: </p>
<hr />
<div>{{Version|7.10.0}}<br />
<br />
= Database Migration with OX App Suite v7.10.0 =<br />
<br />
OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read this paper carefully to ensure a smooth and clean upgrade process.<br />
<br />
== Change Overview ==<br />
<br />
The most significant changes are:<br />
* New version and configuration requirements.<br />
* Most VARCHAR columns need to migrated to utf8mb4 character encoding.<br />
* A major rewrite of the calendar application requires full data migration.<br />
<br />
We strongly recommend to thoroughly plan and test the upgrade procedure. To gain insights about update task runtimes and the expected load, our recommendation is to clone ConfigDB and the biggest UserDB and perform an isolated test upgrade that especially covers the calendar migration and character encoding changes. Update task durations can be significantly longer than with previous upgrades and the migrations might cause noticeable higher I/O load. Also some additional disk space is needed during and after the migrations.<br />
<br />
== Database System ==<br />
<br />
MySQL Server is supported in versions 5.6 and 5.7 with recent patch levels only and MariaDB Server 10.1 and 10.2 respectively. Support for 5.6/10.1 exists for compatibility reasons and is transitional. We recommend upgrading to 5.7/10.2 as soon as possible. Any database system upgrade must happen before App Suite is upgraded to OX App Suite v7.10.0. Please follow the respective guides of your database vendor carefully.<br />
<br />
Different App Suite and database system versions require different configurations of the DBMS, please follow http://oxpedia.org/wiki/index.php?title=My.cnf to have your database configured in a sane way. Especially the following items require some attention with the upgrade to App Suite 7.10.0 and upgrades of the DBMS itself:<br />
<br />
* Supported SQL modes are only <code>NO_ENGINE_SUBSTITUTION</code> and <code>NO_AUTO_CREATE_USER</code>. Starting with App Suite 7.10.0, <code>ONLY_FULL_GROUP_BY</code> is also supported for MySQL 5.7. It is still not with older versions of MySQL or any MariaDB version! To review the current value, use <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'sql_mode';</code>.<br />
* Ensure that <code>character_set_server</code> is set to <code>utf8</code> for App Suite 7.8.x. Again the current global default value can be obtained via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'character_set_server';</code>. With 7.10.0 being fully rolled out, this setting must then be changed to <code>utf8mb4</code>.<br />
<br />
<br />
== Upgrade Procedure ==<br />
<br />
The upgrade to OX App Suite v7.10.0 can be performed like any other major upgrade before. However, the duration of blocking database update tasks for the mentioned charset and calendar migrations could conflict with customers’ availability demands. Therefore it is possible to decouple these special time- and resource-intensive tasks from the plain version upgrade. In this section a multi-step approach is described that performs the version upgrade before and independently from the migrations. Every step always results in a working system that is ready to serve user traffic. Some functional implications that affect user experience are outlined in the according subsections.<br />
<br />
'''Important:''' Even though the first step leads to a basically working OX App Suite v7.10.0 environment, the subsequent steps are not optional but mandatory! Running OX App Suite v7.10.0 in production without having all parts of the migration fulfilled is not supported – OX support will request you to complete the migration tasks when reporting issues that are not related to the migration itself.<br />
<br />
== Initial OX App Suite v7.10.0 Rollout ==<br />
If needed and not done so far, upgrade your MySQL installation to a version supported with OX App Suite v7.10.0 but configure it to be compatible with OX App Suite v7.8.x as described in the “Database System” section.<br />
<br />
Despite the fact that the two special migrations for calendar and character sets are explicitly skipped, this section assumes that the “Rolling Upgrade with breaking Hazelcast upgrade” is applied as described in http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster. For the application server upgrade, the common guide from http://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages can be followed.<br />
<br />
Prepare a dedicated App Suite middleware node that will be used to perform the database update tasks. The node must not be serving any user traffic and be prepared with<br />
<br />
* OX App Suite v7.10.0 packages<br />
* Configuration according to the user production nodes<br />
* The Hazelcast rolling upgrade compatibility package (see http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Rolling_Upgrade_with_breaking_Hazelcast_upgrade)<br />
* Exclude the update tasks for both mentioned migrations. See “Update Task Exclusion” for details.<br />
* Execute update tasks according to your preferred strategy. More on this can be found at http://oxpedia.org/wiki/index.php?title=UpdateTasks.<br />
<br />
After complete and successful update task execution, roll out OX App Suite v7.10.0 to one node after another. After complete rollout, reconfigure MySQL if appropriate as described in the “Database System” section.<br />
<br />
=== Update Task Exclusion ===<br />
<br />
Add the following lines to <code>/opt/open-xchange/etc/excludedupdatetasks.properties</code> or remove the leading # character if already included, so that it contains these two lines:<br />
<br />
# Character Encoding Migration<br />
com.openexchange.groupware.update.excludedUpdateTasks=groupware.utf8mb4<br />
<br />
# Calendar Migration<br />
com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask<br />
<br />
The first line does not denote one dedicated update task, but a whole list of tasks. To make exclusion more convenient, the concept of update task namespaces has been introduced. All update tasks belonging to the character encoding migration are part of the <code>groupware.utf8mb4</code> namespace. The denoted property takes care of excluding them all at once. You can list all according tasks with the <code>/opt/open-xchange/sbin/listUpdateTaskNamespaces</code> tool.<br />
<br />
== Character Encoding Migration ==<br />
<br />
The default character encoding for Unicode (named character set by MySQL) of MySQL will become <code>utf8mb4</code> in the near future. MariaDB on Debian Stretch (9) already has an according default configuration set when installing it from distribution packages. So far all VARCHAR columns are supposed to store at max. 3-byte UTF-8 characters due to the nature of MySQL’s utf8 character encoding. This leads to the fact that for example emojis cannot be saved as part of any App Suite entities. In a mixed-mode scenario (App Suite considers MySQL to operate in utf8mb4 mode due to the <code>character_set_server</code> setting, while columns are specified with utf8 encoding), this leads to issues whenever certain collations during SELECT statements are enforced. To avoid such issues generally and also increase user experience by finally allowing characters from the Unicode astral plane, Open-Xchange has decided to migrate existing data structures to the utf8mb4 character encoding.<br />
<br />
This migration can be executed before or after the calendar migration, while it is recommend to execute it before.<br />
<br />
The upgrade procedure is basically the same as above in terms executing update tasks, while the server software is already up to date and needs no further upgrades:<br />
<br />
* Again prepare one dedicated node that doesn’t serve any user traffic<br />
* Remove the according namespace property from <code>excludedupdatetasks.properties</code> again, but still keep the “ChronosStorageMigrationTask”. Afterwards restart the open-xchange daemon.<br />
* Execute update tasks according to your preferred strategy.<br />
<br />
'''Important:''' The update tasks require a lot of tables to be copied and re-created, leading to high I/O and especially sequential read and write operations. For every copied table the needed MySQL disk space doubles during the update task, so ensure enough free space before running the migration.<br />
<br />
== Calendar Data Migration ==<br />
<br />
The new calendar stack in OX App Suite v7.10.0 comes along with a new data model using its very own tables in MySQL. To preserve users calendar data, an update task <code>com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask</code> has been introduced, that reads all data from the old tables, applies transformations to match the new stack and writes it into the new tables. The approach and upgrade process is described in detail at https://documentation.open-xchange.com/7.10.0/middleware/components/calendar/data_migration.html. Please read that article carefully before continuing. Especially we want to emphasize again the recommendation to test the migration with a copy of your real data to exclude or determine any issues beforehand.<br />
<br />
Before executing this update task, OX App Suite v7.10.0 uses the new calendar stack on top of the old database tables through a compatibility layer. As the old storage layout lacks certain functionality, not all features are functional in between the application upgrade and execution of the update task. Due to this fact, a few spots are affected where not all appointment data that the user interface allows to enter can be persisted. This includes:<br />
<br />
* Reminders, where still only one notification prior the appointment start is possible<br />
* Colors, that cannot be mapped to the previously used labels<br />
* 4-byte UTF-8 characters (emojis) are not yet possible<br />
* Secret appointments, that are still stored as private ones<br />
* An appointment's end timezone can't be applied, if it's different from the start timezone<br />
<br />
Operators of ''non-Galera'' MySQL setups - i.e. Master-Slave replication - can potentially speed up the migration by configuring <code>com.openexchange.calendar.migration.intermediateCommits = false</code>. Per default the migration is performed in batches that separately committed, as Galera does not cope well with large transactions. By changing the setting to <code>false</code>, a single transaction with batch-mode enabled is used.<br />
<br />
'''Important:''' The migrating of calendar data actually leads to a duplication of that data. Also with OX App Suite v7.10.0 every new calendar data is written to both, the old and the new tables redundantly to preserve to ability to roll back to OX App Suite v7.8.4. However, only the parts can preserved that match the old data model. I.e. additional features like multiple reminders or subscriptions of external calendars (Google Calendar, SchedJoules) cannot be preserved during a rollback.<br />
<br />
A repeated OX App Suite v7.10.0 upgrade after a former rollback to OX App Suite v7.8.4 requires to force re-execution of this update task!</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=My.cnf&diff=24056My.cnf2018-06-21T09:56:01Z<p>Steffen.templin: </p>
<hr />
<div>== Introduction ==<br />
<br />
This page lists some performance tuning parameters which we recommend for tuning MySQL database services used for Open-Xchange installations.<br />
<br />
We cannot guarantee this is an exhaustive list of required settings. So treat this list of tunings as probably required, but not necessarily sufficient settings for optimal MySQL performance.<br />
<br />
Furthermore, as MySQL changes over time, settings which have been correct as of the time of writing may become incorrect later.<br />
<br />
However, this list of settings is the result of internal performance testing and real world customer feedback, so it should be valid to some extent.<br />
<br />
In the end, proper configuration of the database service for performance, but also consistency, durability and high availability is in the responsibility of the customer.<br />
<br />
=== Performance items ===<br />
<br />
* You should adjust the <code>innodb_buffer_pool_size</code> parameter for reasonable memory usage. Our DB sizing is mainly memory-driven and this is where most of the memory goes. Our standard DB machine sizing assumption is 32 GB if MySQL dedicated memory on a 48 GB total memory machine. On such a machine, you would configure 32 GB for the innodb_buffer_pool size, being aware that MySQL does also require memory for other things, in particular there are some also per-connection related memory spendings, which can become substantial if you allow for a lot of maximum concurrent connections. Please watch your memory configuration carefully, use monitoring and tools like mysqltuner.pl.<br />
<br />
* On bigger installations you should use <code>innodb_file_per_table = 1</code>, which is creating single files instead of one big blob. If you change this parameter after the database initialization you have to recreate (like dump/drop and re-import) the tables.<br />
<br />
* It can help to put different parts of the mysql datadir (iblog, ibdata) on different filesystems / storage devices. This depends on your infrastructure. Settings herefore are <code>datadir</code>, <code>innodb_data_home_dir</code>, <code>innodb_log_group_home_dir</code>.<br />
<br />
* If your storage is fast (handle a lot of IOPS), you may want to adjust the <code>innodb_io_capacity</code> setting, which defines a limit for the IOPS MySQL will create. The default is 200, which is sensible for single spindle disks. But if you have storage appliances with a lot of fast SAS drives, or even SSDs, this limit can be increased greatly.<br />
<br />
=== Functional items ===<br />
<br />
* Query cache is to be switched off; as we found in our own benchmarks and as backed up by upstreams, this hurts performance in load situations with high concurrency. [https://dev.mysql.com/doc/refman/5.7/en/query-cache.html|The query cache is deprecated as of MySQL 5.7.20, and is removed in MySQL 8.0], so we recommend also to switch that off.<br />
* Starting with App Suite 7.10.0, <code>character_set_server</code> must be set to <code>utf8mb4</code> and <code>collation_server</code> to <code>utf8_general_ci</code><br />
* Starting with MySQL 5.7 <code>innodb_strict_mode</code> must be disabled.<br />
* Starting with MySQL 5.7 and MariaDB 10.2 <code>sql_mode</code> must be configured according to belows matrix.<br />
<br />
==== SQL mode matrix ====<br />
<br />
The default for the <code>sql_mode</code> setting changes regularly with MariaDB and MySQL releases and is not even consistent anymore between the two derivates. SQL modes affect how data and queries are handled at runtime. Enabling strict modes might lead to errors in terms of failing queries or even update tasks. We strongly recommend the following configuration to avoid according runtime errors:<br />
<br />
{| class="wikitable"<br />
|-<br />
! scope="col"| sql_mode<br />
! scope="col"| App Suite 7.8.4<br />
! scope="col"| App Suite 7.10.0<br />
|-<br />
! scope="row"| MySQL 5.6<br />
| <code>NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_ENGINE_SUBSTITUTION</code><br />
|-<br />
! scope="row"| MySQL 5.7<br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION,ONLY_FULL_GROUP_BY</code><br />
|-<br />
! scope="row"| MariaDB 10.1<br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
|-<br />
! scope="row"| MariaDB 10.2<br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
| <code>NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION</code><br />
|-<br />
|}<br />
<br />
=== Sample config files ===<br />
<br />
For easy deployment we recommend not to edit existing the existing my.cnf file, rather assume the distro provides sane settings for most of the items and override items where needed.<br />
<br />
As in MySQL there is a [https://dev.mysql.com/doc/refman/5.7/en/option-files.html last instance wins] semantic in options file parsing, we propose to create a custom include directory "ox.conf.d", put our custom config files therein, and include this directory as latest directory in /etc/mysql/my.cnf.<br />
<br />
To put in that directory, we have one main tuning file called tunings.cnf, one galera-related file if galera is in use, and one more galera host-specific file which contains per-host settings if using galera (separate in a file of its own for easier configuration management).<br />
<br />
So, start with adding to the existing my.cnf at the very bottom:<br />
<br />
!includedir /etc/mysql/ox.conf.d/<br />
<br />
Create that directory and put in there the generic ox tunings file /etc/mysql/ox.conf.d/tunings.cnf:<br />
<br />
[mysqld]<br />
bind-address = *<br />
<br />
#innodb_use_native_aio = 0<br />
<br />
table_open_cache = 3072<br />
table_definition_cache = 4096<br />
max_heap_table_size = 64M<br />
tmp_table_size = 64M<br />
max_connections = 505<br />
max_user_connections = 500<br />
max_allowed_packet = 16M<br />
thread_cache_size = 32<br />
query_cache_size = 0<br />
query_cache_type = 0<br />
default_storage_engine = InnoDB<br />
innodb_buffer_pool_size = 32G<br />
# the default value in MySQL 5.6.6 and higher is 8 when innodb_buffer_pool_size is greater than or equal to 1GB. Otherwise, the default is 1. <br />
innodb_buffer_pool_instances = 32<br />
innodb_data_file_path = ibdata1:128M:autoextend<br />
innodb_file_per_table = 1<br />
# innodb_log_file_size should be 25% of the innodb_buffer_pool_size<br />
innodb_log_file_size = 4GB<br />
# default and recommended value is 2<br />
innodb_log_files_in_group = 2<br />
# adjust according to your storage<br />
#innodb_io_capacity = 1000<br />
<br />
# we are unsure about this setting. Newer versions of MariaDB seem to be fine with low (=1) settings for this value.<br />
# Traditionally we encountered values up to 4x the number of cores.<br />
# Default seems to be number of cores, so let's stick the default<br />
# In the end, we need to leave this setting up to you: if you dont get full cpu utilization in cpu-bound situations, this might be a setting to increase.<br />
#thread_pool_size = 32<br />
<br />
binlog_cache_size = 1M<br />
sync_binlog = 8<br />
binlog_format = row<br />
<br />
character_set_server = utf8<br />
collation_server = utf8_general_ci<br />
<br />
# This was default_table_type previous to MySQL 5.5<br />
default_storage_engine = InnoDB<br />
<br />
innodb_autoinc_lock_mode = 2<br />
<br />
# keep until 5.6, deprecated later<br />
innodb_locks_unsafe_for_binlog = 1<br />
<br />
# we found this has huge impact on (galera) performance<br />
# default (consistent) setting of 1 greatly severs performance<br />
# in galera (or async master-slave) deployments, you might be ok with setting this to 0 or 2,<br />
# assuming our consistency / availability comes from replication / other cluster nodes<br />
innodb_flush_log_at_trx_commit = 0<br />
<br />
# for performance testing systems, to not use excessive disk space<br />
#expire_logs_days = 1<br />
<br />
# MySQL 5.7.7 has changed the default to 1. Disable it explicitly to prevent from errors based on invalid data stored by former App Suite or MySQL versions.<br />
innodb_strict_mode = 0<br />
<br />
# The following value refers to App Suite 7.10 on top of MySQL 5.7. For other combinations see the sql mode matrix at http://oxpedia.org/wiki/index.php?title=My.cnf.<br />
sql_mode = NO_ENGINE_SUBSTITUTION,NO_AUTO_CREATE_USER,ONLY_FULL_GROUP_BY<br />
<br />
If using galera, use the following galera configuration file /etc/mysql/ox.conf.d/wsrep.cnf:<br />
<br />
[mysqld]<br />
# adjust for your distros SO location<br />
wsrep_provider=/usr/lib/libgalera_smm.so<br />
<br />
# this is the big winner and enables us to switch off OX's replication monitor<br />
wsrep_sync_wait=1<br />
<br />
# pick a unique cluster name<br />
wsrep_cluster_name=devcluster<br />
# adjust for your IPs / hostnames<br />
wsrep_cluster_address=gcomm://10.20.29.68,10.20.29.69,10.20.29.70<br />
<br />
# put this in host.cnf<br />
#wsrep_node_name=...<br />
#wsrep_node_address=...<br />
<br />
wsrep_sst_method=xtrabackup-v2<br />
# wsrep_sst_auth if of format username:password<br />
# pick whatever you configured on the donor node<br />
wsrep_sst_auth=sstuser:...<br />
<br />
# galera-specific tunings<br />
wsrep_slave_threads = 32<br />
pxc_strict_mode=ENFORCING<br />
<br />
Galera-related host-specific settings go in /etc/mysql/ox.conf.d/host.cnf:<br />
<br />
[mysqld]<br />
# the nodes hostname<br />
wsrep_node_name=...<br />
# and the IP of the wsrep relevant interface, if multiple<br />
wsrep_node_address=10.20.29.68</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:7_10_Database_Migration&diff=24055AppSuite:7 10 Database Migration2018-06-20T07:26:34Z<p>Steffen.templin: </p>
<hr />
<div>{{Version|7.10.0}}<br />
<br />
= Database Migration with OX App Suite v7.10.0 =<br />
<br />
OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read this paper carefully to ensure a smooth and clean upgrade process.<br />
<br />
== Change Overview ==<br />
<br />
The most significant changes are:<br />
* New version and configuration requirements.<br />
* Most VARCHAR columns need to migrated to utf8mb4 character encoding.<br />
* A major rewrite of the calendar application requires full data migration.<br />
<br />
We strongly recommend to thoroughly plan and test the upgrade procedure. To gain insights about update task runtimes and the expected load, our recommendation is to clone ConfigDB and the biggest UserDB and perform an isolated test upgrade that especially covers the calendar migration and character encoding changes. Update task durations can be significantly longer than with previous upgrades and the migrations might cause noticeable higher I/O load. Also some additional disk space is needed during and after the migrations.<br />
<br />
== Database System ==<br />
<br />
MySQL Server is supported in versions 5.6 and 5.7 with recent patch levels only and MariaDB Server 10.0 and 10.2 respectively. Support for 5.6/10.0 exists for compatibility reasons and is transitional. We recommend upgrading to 5.7 as soon as possible. Any database system upgrade must happen before App Suite is upgraded to OX App Suite v7.10.0. Please follow the respective guides of your database vendor carefully.<br />
<br />
When running MySQL in version 5.7, the required configuration differs between OX App Suite v7.10.0 and former versions. As long as older App Suite versions are serving user traffic, the following configuration options must be applied:<br />
<br />
* Remove <code>ONLY_FULL_GROUP_BY</code> from the <code>sql_mode</code> setting if it is contained there . By default this is the case for MySQL 5.7. but not MariaDB in any version. If <code>sql_mode</code> is not set in <code>my.cnf</code> so far, obtain the default via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'sql_mode';</code>, remove <code>ONLY_FULL_GROUP_BY</code> from it and set the final result as value in <code>my.cnf</code>.<br />
* Ensure that <code>character_set_server</code> is set to <code>utf8</code>. Again the current global default value can be obtained via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'character_set_server';</code>.<br />
<br />
After the upgrade to OX App Suite v7.10.0, these settings need to be adjusted again to fulfil the new requirements:<br />
* Add <code>ONLY_FULL_GROUP_BY</code> to the <code>sql_mode</code> setting or remove the setting as a whole again to fall back to the internal default.<br />
* Change <code>character_set_server</code> to <code>utf8mb4</code>.<br />
<br />
== Upgrade Procedure ==<br />
<br />
The upgrade to OX App Suite v7.10.0 can be performed like any other major upgrade before. However, the duration of blocking database update tasks for the mentioned charset and calendar migrations could conflict with customers’ availability demands. Therefore it is possible to decouple these special time- and resource-intensive tasks from the plain version upgrade. In this section a multi-step approach is described that performs the version upgrade before and independently from the migrations. Every step always results in a working system that is ready to serve user traffic. Some functional implications that affect user experience are outlined in the according subsections.<br />
<br />
'''Important:''' Even though the first step leads to a basically working OX App Suite v7.10.0 environment, the subsequent steps are not optional but mandatory! Running OX App Suite v7.10.0 in production without having all parts of the migration fulfilled is not supported – OX support will request you to complete the migration tasks when reporting issues that are not related to the migration itself.<br />
<br />
== Initial OX App Suite v7.10.0 Rollout ==<br />
If needed and not done so far, upgrade your MySQL installation to a version supported with OX App Suite v7.10.0 but configure it to be compatible with OX App Suite v7.8.x as described in the “Database System” section.<br />
<br />
Despite the fact that the two special migrations for calendar and character sets are explicitly skipped, this section assumes that the “Rolling Upgrade with breaking Hazelcast upgrade” is applied as described in http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster. For the application server upgrade, the common guide from http://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages can be followed.<br />
<br />
Prepare a dedicated App Suite middleware node that will be used to perform the database update tasks. The node must not be serving any user traffic and be prepared with<br />
<br />
* OX App Suite v7.10.0 packages<br />
* Configuration according to the user production nodes<br />
* The Hazelcast rolling upgrade compatibility package (see http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Rolling_Upgrade_with_breaking_Hazelcast_upgrade)<br />
* Exclude the update tasks for both mentioned migrations. See “Update Task Exclusion” for details.<br />
* Execute update tasks according to your preferred strategy. More on this can be found at http://oxpedia.org/wiki/index.php?title=UpdateTasks.<br />
<br />
After complete and successful update task execution, roll out OX App Suite v7.10.0 to one node after another. After complete rollout, reconfigure MySQL if appropriate as described in the “Database System” section.<br />
<br />
=== Update Task Exclusion ===<br />
<br />
Add the following lines to <code>/opt/open-xchange/etc/excludedupdatetasks.properties</code> or remove the leading # character if already included, so that it contains these two lines:<br />
<br />
# Character Encoding Migration<br />
com.openexchange.groupware.update.excludedUpdateTasks=groupware.utf8mb4<br />
<br />
# Calendar Migration<br />
com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask<br />
<br />
The first line does not denote one dedicated update task, but a whole list of tasks. To make exclusion more convenient, the concept of update task namespaces has been introduced. All update tasks belonging to the character encoding migration are part of the <code>groupware.utf8mb4</code> namespace. The denoted property takes care of excluding them all at once. You can list all according tasks with the <code>/opt/open-xchange/sbin/listUpdateTaskNamespaces</code> tool.<br />
<br />
== Character Encoding Migration ==<br />
<br />
The default character encoding for Unicode (named character set by MySQL) of MySQL will become <code>utf8mb4</code> in the near future. MariaDB on Debian Stretch (9) already has an according default configuration set when installing it from distribution packages. So far all VARCHAR columns are supposed to store at max. 3-byte UTF-8 characters due to the nature of MySQL’s utf8 character encoding. This leads to the fact that for example emojis cannot be saved as part of any App Suite entities. In a mixed-mode scenario (App Suite considers MySQL to operate in utf8mb4 mode due to the <code>character_set_server</code> setting, while columns are specified with utf8 encoding), this leads to issues whenever certain collations during SELECT statements are enforced. To avoid such issues generally and also increase user experience by finally allowing characters from the Unicode astral plane, Open-Xchange has decided to migrate existing data structures to the utf8mb4 character encoding.<br />
<br />
This migration can be executed before or after the calendar migration, while it is recommend to execute it before.<br />
<br />
The upgrade procedure is basically the same as above in terms executing update tasks, while the server software is already up to date and needs no further upgrades:<br />
<br />
* Again prepare one dedicated node that doesn’t serve any user traffic<br />
* Remove the according namespace property from <code>excludedupdatetasks.properties</code> again, but still keep the “ChronosStorageMigrationTask”. Afterwards restart the open-xchange daemon.<br />
* Execute update tasks according to your preferred strategy.<br />
<br />
'''Important:''' The update tasks require a lot of tables to be copied and re-created, leading to high I/O and especially sequential read and write operations. For every copied table the needed MySQL disk space doubles during the update task, so ensure enough free space before running the migration.<br />
<br />
== Calendar Data Migration ==<br />
<br />
The new calendar stack in OX App Suite v7.10.0 comes along with a new data model using its very own tables in MySQL. To preserve users calendar data, an update task <code>com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask</code> has been introduced, that reads all data from the old tables, applies transformations to match the new stack and writes it into the new tables. The approach and upgrade process is described in detail at https://documentation.open-xchange.com/7.10.0/middleware/components/calendar/data_migration.html. Please read that article carefully before continuing. Especially we want to emphasize again the recommendation to test the migration with a copy of your real data to exclude or determine any issues beforehand.<br />
<br />
Before executing this update task, OX App Suite v7.10.0 uses the new calendar stack on top of the old database tables through a compatibility layer. As the old storage layout lacks certain functionality, not all features are functional in between the application upgrade and execution of the update task. Due to this fact, a few spots are affected where not all appointment data that the user interface allows to enter can be persisted. This includes:<br />
<br />
* Reminders, where still only one notification prior the appointment start is possible<br />
* Colors, that cannot be mapped to the previously used labels<br />
* 4-byte UTF-8 characters (emojis) are not yet possible<br />
* Secret appointments, that are still stored as private ones<br />
* An appointment's end timezone can't be applied, if it's different from the start timezone<br />
<br />
Operators of ''non-Galera'' MySQL setups - i.e. Master-Slave replication - can potentially speed up the migration by configuring <code>com.openexchange.calendar.migration.intermediateCommits = false</code>. Per default the migration is performed in batches that separately committed, as Galera does not cope well with large transactions. By changing the setting to <code>false</code>, a single transaction with batch-mode enabled is used.<br />
<br />
'''Important:''' The migrating of calendar data actually leads to a duplication of that data. Also with OX App Suite v7.10.0 every new calendar data is written to both, the old and the new tables redundantly to preserve to ability to roll back to OX App Suite v7.8.4. However, only the parts can preserved that match the old data model. I.e. additional features like multiple reminders or subscriptions of external calendars (Google Calendar, SchedJoules) cannot be preserved during a rollback.<br />
<br />
A repeated OX App Suite v7.10.0 upgrade after a former rollback to OX App Suite v7.8.4 requires to force re-execution of this update task!</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:7_10_Database_Migration&diff=24050AppSuite:7 10 Database Migration2018-06-15T11:02:16Z<p>Steffen.templin: </p>
<hr />
<div>{{Version|7.10.0}}<br />
<br />
= Database Migration with OX App Suite v7.10.0 =<br />
<br />
OX App Suite v7.10.0 introduces significant changes regarding the underlying MySQL database system that require special attention in case of upgrades from former versions. Please read this paper carefully to ensure a smooth and clean upgrade process.<br />
<br />
== Change Overview ==<br />
<br />
The most significant changes are:<br />
* New version and configuration requirements.<br />
* Most VARCHAR columns need to migrated to utf8mb4 character encoding.<br />
* A major rewrite of the calendar application requires full data migration.<br />
<br />
We strongly recommend to thoroughly plan and test the upgrade procedure. To gain insights about update task runtimes and the expected load, our recommendation is to clone ConfigDB and the biggest UserDB and perform an isolated test upgrade that especially covers the calendar migration and character encoding changes. Update task durations can be significantly longer than with previous upgrades and the migrations might cause noticeable higher I/O load. Also some additional disk space is needed during and after the migrations.<br />
<br />
== Database System ==<br />
<br />
MySQL Server is supported in versions 5.6 and 5.7 with recent patch levels only and MariaDB Server 10.0 and 10.2 respectively. Support for 5.6/10.0 exists for compatibility reasons and is transitional. We recommend upgrading to 5.7 as soon as possible. Any database system upgrade must happen before App Suite is upgraded to OX App Suite v7.10.0. Please follow the respective guides of your database vendor carefully.<br />
<br />
When running MySQL in version 5.7, the required configuration differs between OX App Suite v7.10.0 and former versions. As long as older App Suite versions are serving user traffic, the following configuration options must be applied:<br />
<br />
* Remove <code>ONLY_FULL_GROUP_BY</code> from the <code>sql_mode</code> setting if it is contained there . By default this is the case for MySQL 5.7. but not MariaDB in any version. If <code>sql_mode</code> is not set in <code>my.cnf</code> so far, obtain the default via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'sql_mode';</code>, remove <code>ONLY_FULL_GROUP_BY</code> from it and set the final result as value in <code>my.cnf</code>.<br />
* Ensure that <code>character_set_server</code> is set to <code>utf8</code>. Again the current global default value can be obtained via <code>SHOW GLOBAL VARIABLES WHERE Variable_name = 'character_set_server';</code>.<br />
<br />
After the upgrade to OX App Suite v7.10.0, these settings need to be adjusted again to fulfil the new requirements:<br />
* Add <code>ONLY_FULL_GROUP_BY</code> to the <code>sql_mode</code> setting or remove the setting as a whole again to fall back to the internal default.<br />
* Change <code>character_set_server</code> to <code>utf8mb4</code>.<br />
<br />
== Upgrade Procedure ==<br />
<br />
The upgrade to OX App Suite v7.10.0 can be performed like any other major upgrade before. However, the duration of blocking database update tasks for the mentioned charset and calendar migrations could conflict with customers’ availability demands. Therefore it is possible to decouple these special time- and resource-intensive tasks from the plain version upgrade. In this section a multi-step approach is described that performs the version upgrade before and independently from the migrations. Every step always results in a working system that is ready to serve user traffic. Some functional implications that affect user experience are outlined in the according subsections.<br />
<br />
'''Important:''' Even though the first step leads to a basically working OX App Suite v7.10.0 environment, the subsequent steps are not optional but mandatory! Running OX App Suite v7.10.0 in production without having all parts of the migration fulfilled is not supported – OX support will request you to complete the migration tasks when reporting issues that are not related to the migration itself.<br />
<br />
== Initial OX App Suite v7.10.0 Rollout ==<br />
If needed and not done so far, upgrade your MySQL installation to a version supported with OX App Suite v7.10.0 but configure it to be compatible with OX App Suite v7.8.x as described in the “Database System” section.<br />
<br />
Despite the fact that the two special migrations for calendar and character sets are explicitly skipped, this section assumes that the “Rolling Upgrade with breaking Hazelcast upgrade” is applied as described in http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Updating_a_Cluster. For the application server upgrade, the common guide from http://oxpedia.org/wiki/index.php?title=AppSuite:UpdatingOXPackages can be followed.<br />
<br />
Prepare a dedicated App Suite middleware node that will be used to perform the database update tasks. The node must not be serving any user traffic and be prepared with<br />
<br />
* OX App Suite v7.10.0 packages<br />
* Configuration according to the user production nodes<br />
* The Hazelcast rolling upgrade compatibility package (see http://oxpedia.org/wiki/index.php?title=AppSuite:Running_a_cluster#Rolling_Upgrade_with_breaking_Hazelcast_upgrade)<br />
* Exclude the update tasks for both mentioned migrations. See “Update Task Exclusion” for details.<br />
* Execute update tasks according to your preferred strategy. More on this can be found at http://oxpedia.org/wiki/index.php?title=UpdateTasks.<br />
<br />
After complete and successful update task execution, roll out OX App Suite v7.10.0 to one node after another. After complete rollout, reconfigure MySQL if appropriate as described in the “Database System” section.<br />
<br />
=== Update Task Exclusion ===<br />
<br />
Add the following lines to <code>/opt/open-xchange/etc/excludedupdatetasks.properties</code> or remove the leading # character if already included, so that it contains these two lines:<br />
<br />
# Character Encoding Migration<br />
com.openexchange.groupware.update.excludedUpdateTasks=groupware.utf8mb4<br />
<br />
# Calendar Migration<br />
com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask<br />
<br />
The first line does not denote one dedicated update task, but a whole list of tasks. To make exclusion more convenient, the concept of update task namespaces has been introduced. All update tasks belonging to the character encoding migration are part of the <code>groupware.utf8mb4</code> namespace. The denoted property takes care of excluding them all at once. You can list all according tasks with the <code>/opt/open-xchange/sbin/listUpdateTaskNamespaces</code> tool.<br />
<br />
== Character Encoding Migration ==<br />
<br />
The default character encoding for Unicode (named character set by MySQL) of MySQL will become <code>utf8mb4</code> in the near future. MariaDB on Debian Stretch (9) already has an according default configuration set when installing it from distribution packages. So far all VARCHAR columns are supposed to store at max. 3-byte UTF-8 characters due to the nature of MySQL’s utf8 character encoding. This leads to the fact that for example emojis cannot be saved as part of any App Suite entities. In a mixed-mode scenario (App Suite considers MySQL to operate in utf8mb4 mode due to the <code>character_set_server</code> setting, while columns are specified with utf8 encoding), this leads to issues whenever certain collations during SELECT statements are enforced. To avoid such issues generally and also increase user experience by finally allowing characters from the Unicode astral plane, Open-Xchange has decided to migrate existing data structures to the utf8mb4 character encoding.<br />
<br />
This migration can be executed before or after the calendar migration, while it is recommend to execute it before.<br />
<br />
The upgrade procedure is basically the same as above in terms executing update tasks, while the server software is already up to date and needs no further upgrades:<br />
<br />
* Again prepare one dedicated node that doesn’t serve any user traffic<br />
* Remove the according namespace property from <code>excludedupdatetasks.properties</code> again, but still keep the “ChronosStorageMigrationTask”. Afterwards restart the open-xchange daemon.<br />
* Execute update tasks according to your preferred strategy.<br />
<br />
'''Important:''' The update tasks require a lot of tables to be copied and re-created, leading to high I/O and especially sequential read and write operations. For every copied table the needed MySQL disk space doubles during the update task, so ensure enough free space before running the migration.<br />
<br />
== Calendar Data Migration ==<br />
<br />
The new calendar stack in OX App Suite v7.10.0 comes along with a new data model using its very own tables in MySQL. To preserve users calendar data, an update task <code>com.openexchange.chronos.storage.rdb.migration.ChronosStorageMigrationTask</code> has been introduced, that reads all data from the old tables, applies transformations to match the new stack and writes it into the new tables. The approach and upgrade process is described in detail at https://documentation.open-xchange.com/7.10.0/middleware/components/calendar/data_migration.html. Please read that article carefully before continuing. Especially we want to emphasize again the recommendation to test the migration with a copy of your real data to exclude or determine any issues beforehand.<br />
<br />
Before executing this update task, OX App Suite v7.10.0 uses the new calendar stack on top of the old database tables through a compatibility layer. As the old storage layout lacks certain functionality, not all features are functional in between the application upgrade and execution of the update task. Due to this fact, a few spots are affected where not all appointment data that the user interface allows to enter can be persisted. This includes:<br />
<br />
* Reminders, where still only one notification prior the appointment start is possible<br />
* Colors, that cannot be mapped to the previously used labels<br />
* 4-byte UTF-8 characters (emojis) are not yet possible<br />
* Secret appointments, that are still stored as private ones<br />
* An appointment's end timezone can't be applied, if it's different from the start timezone<br />
<br />
'''Important:''' The migrating of calendar data actually leads to a duplication of that data. Also with OX App Suite v7.10.0 every new calendar data is written to both, the old and the new tables redundantly to preserve to ability to roll back to OX App Suite v7.8.4. However, only the parts can preserved that match the old data model. I.e. additional features like multiple reminders or subscriptions of external calendars (Google Calendar, SchedJoules) cannot be preserved during a rollback.<br />
<br />
A repeated OX App Suite v7.10.0 upgrade after a former rollback to OX App Suite v7.8.4 requires to force re-execution of this update task!</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements&diff=23909AppSuite:OX System Requirements2018-04-27T09:35:19Z<p>Steffen.templin: </p>
<hr />
<div>= OX App Suite Requirements - Open-Xchange supported components overview =<br />
<br />
The following table provides an overview about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility. This overview makes no claim to be complete.<br />
<br />
Open-Xchange Server 6 overview tables about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility are available at [[OX_System_Requirements|OX 6 Requirements - Open-Xchange supported components overview]]<br />
<br />
Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]<br />
<br />
== Server Platform Requirements ==<br />
=== General Assumptions ===<br />
Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.<br />
<br />
This means in particular, but not only:<br />
<br />
* Infrastructure is "quasi-static". We don't need to take into account things like VMs coming and going dynamically, dynamic IPs, volatile ("ephemeral") data<br />
* "Database as a service" is not allowed. This typically is a highly customized "MySQL like" storage engine, and not a true MySQL, and we can't control flavor, version, setup, etc. If need for configuration changes is identified, we won't be able to change anything.<br />
<br />
So to summarize: we expect any virtualized platform to behave and work just like a well-known non-virtualized / physical platform.<br />
<br />
Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.<br />
<br />
Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.<br />
<br />
'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''<br />
<br />
=== High Level Design / OS setup ===<br />
Operate services separately (USM, Document/Image Converters) as described in Cluster Setup.<br />
<br />
Clocks between all nodes must be synchronized (e.g. via NTP).<br />
<br />
Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.<br />
<br />
Platform Architecture: 64 bit versions (x84_64) of the supported [[#Software Requirements | Linux distributions]]<br />
<br />
=== Node Sizing ===<br />
* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)<br />
* 4 CPU cores (virtual, physical or hyperthreads)<br />
* Disk space<br />
** 5 GB for OS and software<br />
** <code>2 * system memory</code> of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps<br />
<br />
=== Untested/Unsupported Deployments ===<br />
* Changes to Garbage Collector settings<br />
* Running in containerized environments (Docker, rkt)<br />
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration<br />
* Cloud platform services (PaaS) like database systems (for example AWS RDS)<br />
* Multi-site active-active<br />
<br />
=== Software Requirements ===<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Linux Distribution'''<br />
|'''Supported Java Versions'''<br />
|'''Supported Database'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Suse Linux Enterprise Server 12<br />
|OpenJDK 7<br />
|MariaDB 10.0 <br />
|-<br />
|Red Hat Enterprise Linux 6<br />
|OpenJDK 7<br />
|MySQL 5.1<br />
|-<br />
|Red Hat Enterprise Linux 7<br />
|OpenJDK 8<br />
|MariaDB 5.5<br />
|-<br />
|Debian 8 (Jessie)<br />
|OpenJDK 7<br />
|MySQL 5.5, MariaDB 10.1 <br />
|-<br />
|CentOS 6<br />
|OpenJDK 7<br />
|MySQL 5.1<br />
|-<br />
|CentOS 7<br />
|OpenJDK 8<br />
|MariaDB 5.5 <br />
|-<br />
|Univention Corporate Server 4<br />
|OpenJDK 7<br />
|MySQL 5.5<br />
|-<br />
|}<br />
<br />
'''Please Note: To gain higher availability a setup based on Percona XtraDB Cluster is supported like described in this article: [http://oxpedia.org/wiki/index.php?title=OXLoadBalancingClustering_Database Galera database setup]. Open-Xchange supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database and starting with OX 7.8.0 also version 5.6.x.<br />
<br />
== Desktop Browser (Minimum display resolution: 1024 x 768)==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Browser'''<br />
|'''OX App Suite User Front-End'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Microsoft Internet Explorer 10/11<br />
|v7.6.3<br />
|-<br />
|Microsoft Internet Explorer 11/Edge<br />
|v7.8.3, v7.8.4<br />
|-<br />
|Mozilla Firefox (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|-<br />
|Google Chrome (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|-<br />
|Apple Safari (10.01 & 10.03; Mac OS X only)<br />
|v7.8.3, v7.8.4<br />
|-<br />
|}<br />
<br />
== Mobile Device Support==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Mobile Device'''<br />
|'''Supported Browser'''<br />
|'''OX App Suite User Front-End'''<br />
|'''Minimum Speed Requirements'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|iPhone on iOS 9 / iOS 10 / iOS 11<br />
|Safari<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|-<br />
|Smartphone on Android 4.1 or later<br />
|Chrome (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|}<br />
<br />
== Tablet Support==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Tablet'''<br />
|'''Supported Browser'''<br />
|'''OX App Suite User Front-End'''<br />
|'''Minimum Speed Requirements'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Apple iPad (all devices) on iOS 9 / iOS 10 / iOS 11<br />
|Safari<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|-<br />
|Tablets on Android 4.1 or later<br />
|Chrome (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|}<br />
<br />
== MS Windows / MS Outlook® / OX Updater ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Microsoft_Outlook '''Connector for Microsoft Outlook''']<br />
|'''OX Updater'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|Client PC operating system<br />
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|-<br />
|Supported Outlook versions<br />
|Latest versions of Microsoft Outlook 2010 (each with 32 + 64 bit), Outlook 2013 and Outlook 2016 (each with 32 + 64 bit; no support of "Office 2010 Click-to-Run", "Office Home and Business 2010 Testversion”)<br />
|&nbsp;<br />
|-<br />
|}<br />
<br />
== Calendar/Contact synchronization Apple Mac OS X ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|Calendar synchronization with CalDAV<br />
|Contacts synchronization with CardDAV<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Mac OS X 10.11 (El Capitan)<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|macOS 10.12, 10.13 (Sierra & High Sierra)<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|}<br />
<br />
== Calendar/Contact synchronization Apple iOS ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|Calendar synchronization with CalDAV<br />
|Contacts synchronization with CardDAV<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Apple iOS 9 / iOS 10 / iOS 11<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|}<br />
<br />
== Mobility Solution - Supported- Platforms, Features and Devices ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Feature/Technology/Device'''<br />
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Exchange Active Sync 2.5<br />
|[[File:check.gif]]<br />
|-<br />
|Exchange Active Sync 12.1<br />
|[[File:check.gif]]<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Access and creation of emails<br />
|[[File:check.gif]]<br />
|-<br />
|Personal PIM folder<br />
|[[File:check.gif]] <br />
|-<br />
|Public and Shared PIM folder<br />
|[[File:cross.gif]]<br />
|-<br />
|Global address book<br />
|[[File:check.gif]] <br />
|-<br />
|Push E-Mail<br />
|[[File:check.gif]] <br />
|-<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Windows Phone 8 (latest & previous minor versions), Windows Phone 10 (latest & previous minor versions)<br />
|[[File:check.gif]]<br />
|-<br />
|Apple iOS 9 / iOS 10 / iOS 11<br />
|[[File:check.gif]]<br />
|-<br />
|Android 4.1 or later<br />
|[[File:check.gif]]<br />
|-<br />
|}<br />
<br />
== OX Drive for Clients ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|OX Drive for Windows<br />
|Latest versions of Windows 8, latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|-<br />
|OX Drive for Mac OS<br />
|Mac OS X 10.11 (El Capitan), macOS 10.12, 10.13 (Sierra & High Sierra)<br />
|-<br />
|OX Drive for iOS<br />
|Apple iOS 9, Apple iOS 10, Apple iOS 11<br />
|-<br />
|OX Drive for Android<br />
|Smartphone on Android 4.1 or later with Chrome (latest & previous version), Tablets on Android 4.1 or later with Chrome (latest & previous version)<br />
|-<br />
|}<br />
<br />
== OX Mail for Clients ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform / User Interface'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|OX Mail for iOS<br />
|Apple iOS 9, Apple iOS 10<br />
|-<br />
|OX Mail for Android<br />
|Smartphone on Android 4.3 or later<br />
|-<br />
|}<br />
<br />
== OX Sync App ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform / User Interface'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|OX Sync App for Android<br />
|Smartphone on Android 4.0 or later<br />
|-<br />
|}<br />
<br />
== OX Guard ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform / User Interface'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX Guard since v2.6.0: OX App Suite v7.8.3<br>OX Guard since v2.8.0: OX App Suite v7.8.4<br>OX Guard since v2.10.0: OX App Suite v7.10.0<br />
|-<br />
|Mobile Device and Tablet Support<br />
|Apple iPhone on iOS 9 / iOS 10 / iOS 11: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 9 / iOS 10 / iOS 11: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)<br />
|-<br />
|}<br />
<br />
== eM Client for OX App Suite ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|[http://oxpedia.org/wiki/index.php?title=AppSuite:EM_Client_for_OX_App_Suite '''eM Client for OX App Suite''']<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|Client PC operating system<br />
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|-<br />
|}<br />
<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements&diff=23908AppSuite:OX System Requirements2018-04-27T09:29:37Z<p>Steffen.templin: Incorporate more strict and up-to-date requirements towards the underlying hard- and software infrastructure</p>
<hr />
<div>= OX App Suite Requirements - Open-Xchange supported components overview =<br />
<br />
The following table provides an overview about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility. This overview makes no claim to be complete.<br />
<br />
Open-Xchange Server 6 overview tables about the supported components at the OX User Front-End, Connector for Microsoft Outlook and Connector for Business Mobility are available at [[OX_System_Requirements|OX 6 Requirements - Open-Xchange supported components overview]]<br />
<br />
Information about Maintenance expiries of components, versions and browser support, can be found in the [[AppSuite:Versioning_and_Numbering#Maintenance_expires|Maintenance Expires Table]]<br />
<br />
== Server Platform Requirements ==<br />
=== General Assumptions ===<br />
Open-Xchange App Suite Server (middleware services) is designed to run on physical servers or virtual machines of the same flavor. Cloud environments might be used in terms of Infrastructure as a Service (IaaS), meaning that all components need to be deployed in a classical manner on virtual machines.<br />
<br />
This means in particular, but not only:<br />
<br />
* Infrastructure is "quasi-static". We don't need to take into account things like VMs coming and going dynamically, dynamic IPs, volatile ("ephemeral") data<br />
* "Database as a service" is not allowed. This typically is a highly customized "MySQL like" storage engine, and not a true MySQL, and we can't control flavor, version, setup, etc. If need for configuration changes is identified, we won't be able to change anything.<br />
<br />
So to summarize: we expect any virtualized platform to behave and work just like a well-known non-virtualized / physical platform.<br />
<br />
Especially we expect the virtual hardware to be not over-provisioned. Each VM must have dedicated resources with respect to CPU cores, RAM, IOPS, storage, network bandwidth, network latency, etc.<br />
<br />
Network is expected to be flat, inside one datacenter, no multi-datacenter, no segments. No packet loss, low latency.<br />
<br />
'''Disclaimer: All recommendations below are without guarantee and can differ for specific deployments. For mid- and large-scale setups a detailed deployment planning and sizing tests are mandatory and should be agreed on with OX Professional Services.'''<br />
<br />
=== High Level Design / OS setup ===<br />
Operate services separately (USM, Document/Image Converters) as described in Cluster Setup.<br />
<br />
Clocks between all nodes must be synchronized (e.g. via NTP).<br />
<br />
Open file/max process limits need to be adjusted properly. Based on the used Linux distribution and init system configuration will differ, see Resource Limits for further explanation.<br />
<br />
Platform Architecture: 64 bit versions (x84_64) of the supported [[#Server Platforms | Linux distributions]]<br />
<br />
=== Node Sizing ===<br />
* Max. 8 GB heap per JVM + 4 GB system memory for other daemons and the OS (buffers, caches)<br />
* 4 CPU cores (virtual, physical or hyperthreads)<br />
* Disk space<br />
** 5 GB for OS and software<br />
** <code>2 * system memory</code> of free disk space (i.e. 12 GB RAM => 24 GB free disk space) for file spooling, log files, heap and core dumps<br />
<br />
=== Untested/Unsupported Deployments ===<br />
* Changes to Garbage Collector settings<br />
* Running in containerized environments (Docker, rkt)<br />
* Elasticity/High velocity of nodes going up and down: Services are sometimes stateful and demand static configuration<br />
* Cloud platform services (PaaS) like database systems (for example AWS RDS)<br />
* Multi-site active-active<br />
<br />
== Desktop Browser (Minimum display resolution: 1024 x 768)==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Browser'''<br />
|'''OX App Suite User Front-End'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Microsoft Internet Explorer 10/11<br />
|v7.6.3<br />
|-<br />
|Microsoft Internet Explorer 11/Edge<br />
|v7.8.3, v7.8.4<br />
|-<br />
|Mozilla Firefox (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|-<br />
|Google Chrome (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|-<br />
|Apple Safari (10.01 & 10.03; Mac OS X only)<br />
|v7.8.3, v7.8.4<br />
|-<br />
|}<br />
<br />
== Mobile Device Support==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Mobile Device'''<br />
|'''Supported Browser'''<br />
|'''OX App Suite User Front-End'''<br />
|'''Minimum Speed Requirements'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|iPhone on iOS 9 / iOS 10 / iOS 11<br />
|Safari<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|-<br />
|Smartphone on Android 4.1 or later<br />
|Chrome (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|}<br />
<br />
== Tablet Support==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Tablet'''<br />
|'''Supported Browser'''<br />
|'''OX App Suite User Front-End'''<br />
|'''Minimum Speed Requirements'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Apple iPad (all devices) on iOS 9 / iOS 10 / iOS 11<br />
|Safari<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|-<br />
|Tablets on Android 4.1 or later<br />
|Chrome (latest & previous version)<br />
|v7.8.3, v7.8.4<br />
|3G connections (512/256kBit/s, 350ms latency)<br />
|}<br />
<br />
== MS Windows / MS Outlook® / OX Updater ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|[http://oxpedia.org/wiki/index.php?title=AppSuite:Connector_for_Microsoft_Outlook '''Connector for Microsoft Outlook''']<br />
|'''OX Updater'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|Client PC operating system<br />
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|-<br />
|Supported Outlook versions<br />
|Latest versions of Microsoft Outlook 2010 (each with 32 + 64 bit), Outlook 2013 and Outlook 2016 (each with 32 + 64 bit; no support of "Office 2010 Click-to-Run", "Office Home and Business 2010 Testversion”)<br />
|&nbsp;<br />
|-<br />
|}<br />
<br />
== Calendar/Contact synchronization Apple Mac OS X ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|Calendar synchronization with CalDAV<br />
|Contacts synchronization with CardDAV<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Mac OS X 10.11 (El Capitan)<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|macOS 10.12, 10.13 (Sierra & High Sierra)<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|}<br />
<br />
== Calendar/Contact synchronization Apple iOS ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|Calendar synchronization with CalDAV<br />
|Contacts synchronization with CardDAV<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Apple iOS 9 / iOS 10 / iOS 11<br />
|[[File:check.gif]]<br />
|[[File:check.gif]]<br />
|-<br />
|}<br />
<br />
== Mobility Solution - Supported- Platforms, Features and Devices ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Feature/Technology/Device'''<br />
|[http://oxpedia.org/wiki/index.php?title=OXtender_for_Business_Mobility '''OXtender for Business Mobility'''] (availalble for App Suite, OXHE, OXSE)<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Exchange Active Sync 2.5<br />
|[[File:check.gif]]<br />
|-<br />
|Exchange Active Sync 12.1<br />
|[[File:check.gif]]<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Access and creation of emails<br />
|[[File:check.gif]]<br />
|-<br />
|Personal PIM folder<br />
|[[File:check.gif]] <br />
|-<br />
|Public and Shared PIM folder<br />
|[[File:cross.gif]]<br />
|-<br />
|Global address book<br />
|[[File:check.gif]] <br />
|-<br />
|Push E-Mail<br />
|[[File:check.gif]] <br />
|-<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Windows Phone 8 (latest & previous minor versions), Windows Phone 10 (latest & previous minor versions)<br />
|[[File:check.gif]]<br />
|-<br />
|Apple iOS 9 / iOS 10 / iOS 11<br />
|[[File:check.gif]]<br />
|-<br />
|Android 4.1 or later<br />
|[[File:check.gif]]<br />
|-<br />
|}<br />
<br />
== OX Drive for Clients ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|OX Drive for Windows<br />
|Latest versions of Windows 8, latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|-<br />
|OX Drive for Mac OS<br />
|Mac OS X 10.11 (El Capitan), macOS 10.12, 10.13 (Sierra & High Sierra)<br />
|-<br />
|OX Drive for iOS<br />
|Apple iOS 9, Apple iOS 10, Apple iOS 11<br />
|-<br />
|OX Drive for Android<br />
|Smartphone on Android 4.1 or later with Chrome (latest & previous version), Tablets on Android 4.1 or later with Chrome (latest & previous version)<br />
|-<br />
|}<br />
<br />
== OX Mail for Clients ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform / User Interface'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|OX Mail for iOS<br />
|Apple iOS 9, Apple iOS 10<br />
|-<br />
|OX Mail for Android<br />
|Smartphone on Android 4.3 or later<br />
|-<br />
|}<br />
<br />
== OX Sync App ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform / User Interface'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|OX Sync App for Android<br />
|Smartphone on Android 4.0 or later<br />
|-<br />
|}<br />
<br />
== OX Guard ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|'''System / Platform / User Interface'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX Guard since v2.6.0: OX App Suite v7.8.3<br>OX Guard since v2.8.0: OX App Suite v7.8.4<br>OX Guard since v2.10.0: OX App Suite v7.10.0<br />
|-<br />
|Mobile Device and Tablet Support<br />
|Apple iPhone on iOS 9 / iOS 10 / iOS 11: Safari (latest version & previous version)<br>Smartphone on Android 4.1 or later: Chrome (latest & previous version)<br>Apple iPad (all devices) on iOS 9 / iOS 10 / iOS 11: Safari Safari (latest version & previous version)<br>Tablets on Android 4.1 or later: Chrome (latest & previous version)<br />
|-<br />
|}<br />
<br />
== eM Client for OX App Suite ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Requirement'''<br />
|[http://oxpedia.org/wiki/index.php?title=AppSuite:EM_Client_for_OX_App_Suite '''eM Client for OX App Suite''']<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|OX App Suite<br />
|OX App Suite v7.8.3, OX App Suite v7.8.4<br />
|-<br />
|Client PC operating system<br />
|Latest versions of Windows 8 (no support of start screen tiles), latest versions of Windows 10 (no support of Mac OS X clients with emulators and Windows RT)<br />
|-<br />
|}<br />
<br />
== Server Platforms ==<br />
<br />
{|border="2" rules="all" align="left"><br />
|'''Platforms'''<br />
|'''Supported Java Versions'''<br />
|'''Supported Database'''<br />
|- <br />
|&nbsp;<br />
|&nbsp;<br />
|&nbsp;<br />
|-<br />
|Suse Linux Enterprise Server 12<br />
|OpenJDK 7<br />
|MariaDB 10.0 <br />
|-<br />
|Red Hat Enterprise Linux 6<br />
|OpenJDK 7<br />
|MySQL 5.1<br />
|-<br />
|Red Hat Enterprise Linux 7<br />
|OpenJDK 8<br />
|MariaDB 5.5<br />
|-<br />
|Debian 8 (Jessie)<br />
|OpenJDK 7<br />
|MySQL 5.5, MariaDB 10.1 <br />
|-<br />
|CentOS 6<br />
|OpenJDK 7<br />
|MySQL 5.1<br />
|-<br />
|CentOS 7<br />
|OpenJDK 8<br />
|MariaDB 5.5 <br />
|-<br />
|Univention Corporate Server 4<br />
|OpenJDK 7<br />
|MySQL 5.5<br />
|-<br />
|}<br />
<br />
'''Please Note: To gain higher availability a setup based on Percona XtraDB Cluster is supported like described in this article: [http://oxpedia.org/wiki/index.php?title=OXLoadBalancingClustering_Database Galera database setup]. Open-Xchange supports the "Percona XtraDB Cluster 5.5" flavor of the Galera database and starting with OX 7.8.0 also version 5.6.x.<br />
<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=StrottiTest&diff=23875StrottiTest2018-03-14T09:14:29Z<p>Steffen.templin: </p>
<hr />
<div>Test<br />
Noch ein test<br />
<br />
<br />
...<br />
<br />
qwertz</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=StrottiTest&diff=23874StrottiTest2018-03-14T09:11:41Z<p>Steffen.templin: </p>
<hr />
<div>Test<br />
Noch ein test<br />
<br />
<br />
...</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=StrottiTest&diff=23873StrottiTest2018-03-14T09:08:36Z<p>Steffen.templin: </p>
<hr />
<div>Test<br />
Noch ein test</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Configuration_properties_7.8.4&diff=23845AppSuite:Configuration properties 7.8.42018-02-22T07:35:08Z<p>Steffen.templin: </p>
<hr />
<div>{{Version|7.8.4}}<br />
<br />
The content on this page has moved to https://documentation.open-xchange.com/components/middleware/config/7.8.4/.<br />
<br />
Note: Open-Xchange is in the process of migrating all its technical documentation to a new and improved documentation system (documentation.open-xchange.com). Please note as the migration takes place more information will be available on the new system and less on this system. Thank you for your understanding during this period of transition.<br />
<br />
[[Category:OX6]] [[Category:AppSuite]] [[Category:Administrator]] [[Category:Configuration]] [[Category:Generated]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Versioning_and_Numbering&diff=22456AppSuite:Versioning and Numbering2016-10-17T11:34:20Z<p>Steffen.templin: /* Please Note - Additional Information */</p>
<hr />
<div>=Versioning and Numbering of Open-Xchange Products=<br />
<br />
== Abbreviations ==<br />
<br />
The Open-Xchange versioning 2015 will be structured in the following way:<br><br><br />
'''<generation>.<major release>.<minor release> Rev<build number>'''<br><br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |Abbreviation<br />
!align="left" |Meaning<br />
!align="left" |Comparison<br />
|-<br />
|<generation><br />
|The first number is the product generation number. A new generation may contain new architecture, different technology and many more.<br />
|<font color="#008000">OX App Suite 7</font><font color="#FF0000"></font><br />
|-<br />
|<major release><br />
|The second version number (major release) indicates significant program changes in terms of added functionality. Major changes to design and enhancements of APIs are possible. All APIs shall be backward compatible, which means, that mainly new functions can be added. If Open-Xchange releases a new major release this will be an even number, unstable interim releases have odd numbers.<br />
|<font color="#008000">OX App Suite v7.6</font><font color="#FF0000"> </font><br />
|-<br />
|<minor release><br />
|The third version number (minor releases) indicates an update with consolidated bug fixes and non-intrusive feature enhancements. APIs and database will not be changed if this can be avoided. All changes must be backward compatible.<br />
|<font color="#008000">OX App Suite v7.6.1</font><font color="#FF0000"></font><br />
|-<br />
|<build number><br />
|The Rev-number (Revision) shows the progress of the development in single steps<br />
|<font color="#008000">OX App Suite v7.6.1-Rev3</font><font color="#FF0000"></font><br />
|-<br />
|<br />
|<br />
|<br />
|-<br />
|Public Patch Release / Patch Release<br />
|A Public Patch Release enables Open-Xchange to publish a feature together with a patch. This in turn enables Open-Xchange to react more flexibly to time requests for certain features, thus relieving minor releases and making it possible to shift them. Delivering a feature with a Public Patch Release requires:<br />
* It can be implemented without far-reaching side effects. This is especially true for features that are implemented as plug-ins. To a limited extend, features affecting a limited sub set of core functionality can be included. Technical pragmatism is fine to reach the goal (e.g., copy & paste of functionality instead of abstraction into a service). This pragmatism has to be leveled out though as soon as the feature is ported into a more flexible branch. <br />
*It can be deactivated and is deactivated by default. If a customer installs a Public Patch Release, the familiar feature set does not change. Only if explicitly activating the enhanced features, will they be available to the end user.<br />
*If features require changes to the data base schema or configuration files, they have to be developed in such a way that they do not impair the running system.<br />
*Side-effects of Public Patch Releases are evaluated by the respective developers. Together with the QA team, they make a test plan for checking for those side effects and other effects. <br />
|<br />
|}<br />
<br><br />
<br />
== Release Levels of Open-Xchange ==<br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |<font color="#008000">OX Release Level (new)<br />
!align="left" |<font color="#008000">New Generation<br />
!align="left" |<font color="#008000">Major Release<br />
!align="left" |<font color="#008000">Minor Release<br />
!align="left" |<font color="#008000">Public Patch Release<br />
!align="left" |<font color="#008000">Patch Release<br />
|-<br />
|'''Target Audience'''<br />
|All<br />
|Public/All<br />
|Maintenance customers & Partners<br />
|Public/All<br />
|L3 Support Customers, Value Package Partners<br />
|-<br />
|'''Purpose'''<br />
|Provide new technologies<br />
|Provide functional enhancements including Bug Fixes, accumulate earlier Patch Releases's / major releases. Major changes to design and enhancements of APIs are possible. All APIs shall be backward compatible.<br />
|Provide common bug fixes for all customers, accumulate previous Patch Release's and non-intrusive feature enhancements. APIs and database will not be changed if this can be avoided. All changes must be backward compatible.<br />
|Provide fixes for severity level 1/2 tickets, for all Support Customer, small features (developed in such a way that they do not impair the running system), temporary until next Maintenance Release accumulative.<br />
|Provide fixes for severity level 1/2 tickets, for a specific Support Customer, small features, temporary until next Maintenance Release accumulative<br />
|-<br />
|'''Frequency'''<br />
|Open-Xchange Roadmap<br />
|Decided by Open-Xchange<br />
|Decided by Open-Xchange<br />
|As soon as required<br />
|According to SLA<br />
|-<br />
|'''[[AppSuite:Version_Support_Committment|Support Committment]]'''<br />
|5 years after First Customer Shippment (FCS)<br />
|6 months after FCS (Latest Minor Release at the Major-Release cycle will be official supported)<br />
|Last Minor Release of a supported Major Release<br />
|Next Public Patch Release<br />
|Next (Public) Patch Release<br />
|-<br />
|'''Requested by'''<br />
|Product Management<br />
|Product Management, Professional Services<br />
|Support, QA, Product Management, Professional Services<br />
|Entitled Customer (Support, Professional Services), Product Management<br />
|Entitled Customer (Support, Professional Services)<br />
|-<br />
|'''Compatibility requirements/backward compatibility'''<br />
|<br />
|Database updates, Changes of configuration files<br />
|Backward compatibility to last major release. In urgent cases there could be database updates or configuration file changes<br />
|Backward compatibility to last major release<br />
|Backward compatibility to last major release<br />
|-<br />
|'''Test Efforts OX (QA)'''<br />
|Smoke Tests, Always Tests, Bug Fix Tests, Feature Tests, Dependencies Tests, Heuristic Tests, Performance Tests<br />
|Smoke Tests, Always Tests, Bug Fix Tests, Feature Tests, Dependencies Tests, Heuristic Tests, Performance Tests<br />
|Smoke Test, Always Tests, Bug Fix Tests, Dependencies Tests, Heuristic Tests, Performance Tests<br />
|Smoke Tests, Always Tests, Bug Fix Tests - Fix Approval<br />
|Smoke Tests, Always Tests, Bug Fix Tests - Support: Fix Approval<br />
|-<br />
|'''Test Efforts Customer/Partner'''<br />
|Smoke Tests, Bug Fix Tests, New Feature Tests, Integration Tests<br />
|Smoke Tests, Bug Fix Tests, New Feature Tests, Integration Tests<br />
|Smoke Tests, Bug Fix Tests, Integration Tests<br />
|Smoke Tests<br />
|Smoke Tests, Bug Fix Approval<br />
|-<br />
|}<br />
<br><br />
<br />
== Open-Xchange Server 6 ==<br />
<br />
=== Editions ===<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" width="50"|Abbreviation<br />
!align="left" width="200"|Description<br />
!align="left" |Target usage<br />
|-<br />
|OX:HE<br />
|Open-Xchange Hosting Edition<br />
|Designed for organizations that want to provide a scalable, multi-tenant e-mail and collaboration solution to their customers. Focus: Software-as-a-Service offerings<br />
|-<br />
|OX:SE<br />
|Open-Xchange Server Edition<br />
|Designed for medium and large size organizations, educational institutions and public administrations seeking a customizable communication solution. Focus: System Integrators<br />
|-<br />
|OX:SEforUCS<br />
|Open-Xchange Server Edition for Univention Corporate Server<br />
|Integration to in-house customer environments<br />
|}<br />
<br />
== Open-Xchange App Suite ==<br />
<br />
=== Editions ===<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" width="50"|Abbreviation<br />
!align="left" width="200"|Description<br />
!align="left" |Target usage<br />
|-<br />
|OX App Suite<br />
|Open-Xchange App Suite Community Version<br />
|Need to revitalize business growth and increase your competitive advantage? OX App Suite integrates smoothly into existing infrastructures and massively scales across multi-tenant architectures securely and reliably. Offer your users a seamless messaging experience to deliver branded, app-economy services and take back the user experience. German engineered and designed for a mobile world, OX App Suite uses open API's to deliver device independent access to email and messaging, social collaboration and digital media via a rich web-based interface. Through a modular App-based portal, HTML5 interoperability gives providers a new basis to up-sell and cross-sell white-labeled services and mobile applications.<br />
|}<br />
<br />
== Releases ==<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2007 2007]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2008 2008]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2009 2009]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2010 2010]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2011 2011]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2012 2012]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2013 2013]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2014 2014]===<br />
<br />
===[http://oxpedia.org/wiki/index.php?title=Versioning_and_Numbering_2015 2015]===<br />
<br />
===2016 ===<br />
<br />
'''Please Note: Minor and Major Product Releases in bold'''<br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |GA<br />
!align="left" |Product<br />
!align="left" |Major Release<br />
!align="left" |Minor Release<br />
!align="left" |Public Patch Releases<br />
!align="left" |Shipped Packages<br />
|-<br />
|2016-01-13<br />
|OX App Suite v7.6.2, OX 6 Backend v7.6.2 and Connector for Business Mobility<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev45<br>Open-Xchange App Suite frontend v7.6.2-rev35<br>Open-Xchange EAS v7.6.2-rev20<br />
|-<br />
|2016-01-13<br />
|OX App Suite v7.6.3, OX 6 Backend v7.6.3, OX Updater and Connector for Business Mobility<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev3<br>Open-Xchange App Suite frontend v7.6.3-rev3<br>Open-Xchange EAS v7.6.3-rev3<br>Open-Xchange OX Updater v7.6.3-rev3<br />
|-<br />
|2016-01-13<br />
|OX App Suite v7.8.0, OX 6 Backend v7.8.0 and Connector for Business Mobility<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev16<br>Open-Xchange App Suite frontend v7.8.0-rev14<br>Open-Xchange EAS v7.8.0-rev7<br />
|-<br />
|2016-01-21<br />
|OX Guard v2.2.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.1-rev5<br />
|-<br />
|2016-01-21<br />
|OX Guard v2.0.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.0.0-rev17<br />
|-<br />
|2016-01-21<br />
|OX Guard v2.2.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.0-rev9<br />
|-<br />
|2016-01-25<br />
|X App Suite v7.6.2 and OX 6 Backend v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev46<br>Open-Xchange App Suite frontend v7.6.2-rev36<br>Open-Xchange USM v7.6.2-rev22<br />
|-<br />
|2016-01-25<br />
|X App Suite v7.6.3 and OX 6 Backend v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev5<br>Open-Xchange App Suite frontend v7.6.3-rev4<br />
|-<br />
|2016-01-26<br />
|OX App Suite v7.8.0 and OX 6 Backend v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev20<br>Open-Xchange App Suite frontend v7.8.0-rev15<br />
|-<br />
|2016-02-03<br />
|OX Guard v2.2.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.1-rev6<br />
|-<br />
|2016-02-02<br />
|Connector for Microsoft Outlook<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Connector for Microsoft Outlook v7.2.20<br>Open-Xchange OX Updater Backend Package v7.6.2-rev18<br>Open-Xchange OX Updater Backend Package v7.6.3-rev4<br>Open-Xchange OX Updater Backend Package v7.8.0-rev8<br />
|-<br />
|2016-02-03<br />
|OX Guard v2.2.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.1-rev6<br />
|-<br />
|2016-02-03<br />
|OX Guard v2.0.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.0.0-rev18<br />
|-<br />
|2016-02-08<br />
|OX App Suite v7.6.2 and OX 6 Backend v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev48<br>Open-Xchange App Suite frontend v7.6.2-rev37<br />
|-<br />
|2016-02-08<br />
|OX App Suite v7.6.3 and OX 6 Backend v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev6<br>Open-Xchange App Suite frontend v7.6.3-rev5<br />
|-<br />
|2016-02-15<br />
|OX App Suite v7.8.0 and OX 6 Backend v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev22<br>Open-Xchange App Suite frontend v7.8.0-rev16<br />
|-<br />
|2016-02-18<br />
|Connector for Business Mobility v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange USM v7.6.2-rev23<br>Open-Xchange EAS v7.6.2-rev21<br />
|-<br />
|2016-02-18<br />
|Connector for Business Mobility v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange USM 7.6.3-rev3<br>Open-Xchange EAS 7.6.3-rev4<br />
|-<br />
|2016-02-24<br />
|OX App Suite v7.6.2 and OX 6 Backend v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev49<br>Open-Xchange App Suite frontend v7.6.2-rev39<br />
|-<br />
|2016-02-25<br />
|OX Mail app<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|OX Mail app v1.2.0<br />
|-<br />
|2016-02-29<br />
|OX App Suite v7.6.3 and OX 6 Backend v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev7<br>Open-Xchange App Suite frontend v7.6.3-rev6<br />
|-<br />
|2016-02-29<br />
|OX App Suite v7.8.0 and OX 6 Backend v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev24<br>Open-Xchange App Suite frontend v7.8.0-rev18<br>Open-Xchange USM v7.8.0-rev9<br>Open-Xchange EAS v7.8.0-rev8<br>Open-Xchange App Suite Documentconverter v7.8.0-rev7<br />
|-<br />
|2016-03-01<br />
|OX App Suite v7.6.3 for Univention Corporate Server v3.2 and OX Guard v2.2.1 for Univention Corporate Server v4.1<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange App Suite Middleware (backend) v7.6.3-rev7<br>Open-Xchange App Suite frontend v7.6.3-rev6<br>Open-Xchange USM v7.6.3-rev3<br>Open-Xchange EAS v7.6.3-rev4<br>Open-Xchange OXUpdater v7.6.3-rev3<br>Open-Xchange Drive Restricted v7.6.3-rev3<br>Open-Xchange Documentconverter API v7.6.3-rev2<br>Open-Xchange Documentconverter v7.6.3-rev2<br>Open-Xchange Documents v7.6.3-rev2<br>Open-Xchange Documents frontend v7.6.3-rev2<br>Open-Xchange Readerengine v7.6.3-rev2<br>Open-Xchange Calcengine v7.6.3-rev2<br>Open-Xchange Guard v2.2.1-rev6<br />
|-<br />
|2016-03-07<br />
|OX Guard v2.2.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.1-rev7<br />
|-<br />
|2016-03-10<br />
|OX Messenger v1.4.0<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange Messenger v1.4.0-rev9<br />
|-<br />
|2016-03-14<br />
|OX App Suite v7.6.2 and OX 6 Middleware v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev50<br>Open-Xchange App Suite frontend v7.6.2-rev40<br />
|-<br />
|2016-03-14<br />
|OX App Suite v7.6.3 and OX 6 Middleware v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev8<br>Open-Xchange App Suite frontend v7.6.3-rev7<br />
|-<br />
|2016-03-14<br />
|OX App Suite v7.8.0 and OX 6 Middleware v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev26<br>Open-Xchange App Suite frontend v7.8.0-rev19<br />
|-<br />
|2016-03-17<br />
|OX Drive app v2.0.0 for Windows<br />
|[[File:check.gif]]<br />
|<br />
|<br />
|Open-Xchange OX Updater 7.8.0-rev9 <br>Open-Xchange OX Drive for Windows 2.0.0<br />
|-<br />
|2016-03-17<br />
|Connector for MS Outlook<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Updater v7.8.0-rev9<br>Connector for Microsoft Outlook v7.2.21<br />
|-<br />
|2016-03-29<br />
|OX Drive app v2.0.0 for Apple OS X<br />
|[[File:check.gif]]<br />
|<br />
|<br />
|Open-Xchange OX Drive for Apple OS X 2.0.0<br />
|-<br />
|2016-03-29<br />
|OX App Suite v7.6.2 and OX 6 Middleware v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev51<br>Open-Xchange App Suite frontend v7.6.2-rev41<br />
|-<br />
|2016-03-14<br />
|OX App Suite v7.6.3 and OX 6 Middleware v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev9<br>Open-Xchange App Suite frontend v7.6.3-rev8<br />
|-<br />
|2016-03-29<br />
|OX App Suite v7.8.0 and OX 6 Middleware v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev27<br>Open-Xchange App Suite frontend v7.8.0-rev20<br />
|-<br />
|2016-03-29<br />
|OX Guard v2.2.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.1-rev8<br />
|-<br />
|2016-03-31<br />
|OX App Suite v7.8.1, OX 6 v6.22.11 and OX Documents v7.8.1<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange Middleware 7.8.1-rev7<br>Open-Xchange OX6 Middleware 7.8.1-rev7<br>Open-Xchange App Suite frontend 7.8.1-rev7<br>Open-Xchange OX6 frontend 6.22.11-rev7<br>Open-Xchange USM 7.8.1-rev7<br>Open-Xchange EAS 7.8.1-rev7<br>Open-Xchange OXUpdater 7.8.1-rev7<br>Open-Xchange Drive Restricted 7.8.1-rev7<br>Open-Xchange Documents 7.8.1-rev7<br>Open-Xchange Documents Frontend 7.8.1-rev7<br>Open-Xchange Documents Communication 7.8.1-rev7<br>Open-Xchange Calcengine 7.8.1-rev7<br>Open-Xchange Readerengine 7.8.1-rev7<br>Open-Xchange Documentconverter 7.8.1-rev7<br>Open-Xchange Documentconverter API 7.8.1-rev7<br>Open-Xchange Drive Help 2.0.0-rev1<br>Open-Xchange Drive for Windows 2.0.0<br>Open-Xchange Updater 6.18.31<br>Open-Xchange Connector for Microsoft Outlook 7.2.21<br>Open-Xchange Notifier 1.0.6<br />
|-<br />
|2016-03-31<br />
|OX Guard v2.4.0<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange Guard 2.4.0-rev7<br />
|-<br />
|2016-04-06<br />
|OX App Suite Frontend v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite frontend v7.8.1-rev8<br />
|-<br />
|2016-04-08<br />
|OX App Suite and OX 6 Backend v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite backend v7.8.1-rev8<br />
|-<br />
|2016-04-11<br />
|OX App Suite v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite frontend v7.6.3-rev9<br />
|-<br />
|2016-04-11<br />
|OX App Suite v7.8.0 and OX 6 Backend v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev28<br>Open-Xchange App Suite frontend v7.8.0-rev21<br />
|-<br />
|2016-04-13<br />
|OX Guard v2.2.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.1-rev9<br />
|-<br />
|2016-04-19<br />
|Connector for Microsoft Outlook v7.8.0 & v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Connector for Microsoft Outlook v7.2.22<br>Open-Xchange Updater Backend Package v7.8.0-rev10<br>Open-Xchange Updater Backend Package v7.8.1-rev8<br />
|-<br />
|2016-04-20<br />
|OX Guard v2.0.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.0.0-rev19<br />
|-<br />
|2016-04-21<br />
|OX Guard v2.4.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.4.0-rev8<br />
|-<br />
|2016-04-25<br />
|OX App Suite v7.8.0 and OX 6 Backend v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev29<br>Open-Xchange App Suite frontend v7.8.0-rev22<br />
|-<br />
|2016-04-25<br />
|OX App Suite v7.8.1 and OX 6 Backend v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev9<br>Open-Xchange App Suite frontend v7.8.1-rev9<br />
|-<br />
|2016-04-25<br />
|OX App Suite v7.6.3 and OX 6 Backend v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev10<br>Open-Xchange App Suite frontend v7.6.3-rev10<br />
|-<br />
|2016-04-26<br />
|OX Messenger v1.4.1 for OX App Suite v7.8.1<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange Messenger v1.4.1-rev2<br />
|-<br />
|2016-05-03<br />
|OX Guard v2.4.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.4.0-rev9<br />
|-<br />
|2016-05-10<br />
|OX App Suite v7.6.2, OX 6 Middleware v7.6.2 and OX Documents v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev54<br>Open-Xchange App Suite frontend v7.6.2-rev43<br>Open-Xchange Office v7.6.2-rev14<br />
|-<br />
|2016-05-10<br />
|OX App Suite v7.6.3, OX 6 Middleware v7.6.3 and OX Documents v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev11<br>Open-Xchange App Suite frontend v7.6.3-rev11<br>Open-Xchange Office v7.6.3-rev3<br />
|-<br />
|2016-05-10<br />
|OX App Suite v7.8.0, OX 6 Middleware v7.8.0 and OX Documents v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev30<br>Open-Xchange App Suite frontend v7.8.0-rev23<br>Open-Xchange Office v7.8.0-rev7<br />
|-<br />
|2016-05-10<br />
|OX App Suite v7.8.1, OX 6 Middleware v7.8.1 and OX Documents v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev11<br>Open-Xchange App Suite frontend v7.8.1-rev10<br>Open-Xchange Office v7.8.1-rev8<br>Open-Xchange Documentconverter v7.8.1-rev8<br>Open-Xchange Documentconverter API v7.8.1-rev8<br />
|-<br />
|2016-05-12<br />
|OX Updater v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Updater Backend Packages v7.8.1-rev9<br>Open-Xchange Updater v6.18.32<br>Open-Xchange Connector for Microsoft Outlook v7.2.22<br />
|-<br />
|2016-05-23<br />
|OX App Suite v7.8.1 and OX 6 v6.22.11<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev12<br>Open-Xchange App Suite Frontend v7.8.1-rev11<br>Open-Xchange 6 Frontend v6.22.11-rev8<br />
|-<br />
|2016-05-23<br />
|OX App Suite v7.8.0 and OX 6 v6.22.10<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev31<br>Open-Xchange App Suite Frontend v7.8.0-rev24<br>Open-Xchange OX6 Frontend 6.22.10-rev8<br />
|-<br />
|2016-05-31<br />
|OX Drive app v2.0 for Apple iOS and Android<br />
|[[File:check.gif]]<br />
|<br />
|<br />
|Open-Xchange OX Drive for Apple iOS v2.0.4.2170<br>Open-Xchange OX Drive for Android v2.0.4.467<br />
|-<br />
|2016-05-31<br />
|OX Guard v2.2.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.2.1-rev10<br />
|-<br />
|2016-06-07<br />
|OX App Suite v7.6.2, OX 6 Middleware v7.6.2 and OX Documents v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev55<br>Open-Xchange App Suite frontend v7.6.2-rev44<br>Open-Xchange Office v7.6.2-rev15<br />
|-<br />
|2016-06-07<br />
|OX App Suite v7.6.3, OX 6 Middleware v7.6.3 and OX Documents v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev12<br>Open-Xchange App Suite frontend v7.6.3-rev13<br>Open-Xchange Office v7.6.3-rev3<br />
|-<br />
|2016-06-07<br />
|OX App Suite v7.8.0, OX 6 Middleware v7.8.0 and OX Documents v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev32<br>Open-Xchange App Suite frontend v7.8.0-rev25<br>Open-Xchange Office v7.8.0-rev9<br />
|-<br />
|2016-06-07<br />
|OX App Suite v7.8.1, OX 6 Middleware v7.8.1 and OX Documents v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev14<br>Open-Xchange App Suite frontend v7.8.1-rev12<br>Open-Xchange Office v7.8.1-rev8<br />
|-<br />
|2016-06-21<br />
|OX Mail<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Mobile Push Certificates v1.0.1-rev2<br />
|-<br />
|2016-06-21<br />
|OX App Suite v7.8.0, OX 6 Backend v7.8.0 and Connector for Business Mobility<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev33<br>Open-Xchange App Suite Frontend v7.8.0-rev26<br>Open-Xchange EAS v7.8.0-rev9<br />
|-<br />
|2016-06-21<br />
|OX App Suite v7.8.1, OX 6 Backend v7.8.1 and Connector for Business Mobility<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev15<br>Open-Xchange App Suite Frontend v7.8.1-rev13<br>Open-Xchange EAS v7.8.1-rev8<br />
|-<br />
|2016-06-23<br />
|eM Client for OX App Suite<br />
|[[File:check.gif]]<br />
|<br />
|<br />
|emclient_appsuite_v6.0.26257.msi<br />
|-<br />
|2016-07-04<br />
|OX App Suite v7.6.3 and OX 6 Middleware v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev13<br>Open-Xchange App Suite frontend v7.6.3-rev14<br />
|-<br />
|2016-07-04<br />
|OX App Suite v7.6.2 and OX 6 Middleware v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev57<br />
|-<br />
|2016-07-04<br />
|OX App Suite v7.8.0 and OX 6 Middleware v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev34<br>Open-Xchange App Suite frontend v7.8.0-rev27<br>Open-Xchange USM v7.8.0-rev10<br />
|-<br />
|2016-07-04<br />
|OX App Suite v7.8.1 and OX 6 Middleware v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev16<br>Open-Xchange App Suite frontend v7.8.1-rev14<br>Open-Xchange USM v7.8.1-rev8<br />
|-<br />
|2016-07-13<br />
|OX App Suite v7.8.2, OX 6 v6.22.12, OX Documents v7.8.2 and OX Guard v2.4.2<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange Middleware 7.8.2-rev4<br>Open-Xchange OX6 Middleware 7.8.2-rev4<br>Open-Xchange App Suite frontend 7.8.2-rev4<br>Open-Xchange OX6 frontend 6.22.12-rev4<br>Open-Xchange USM 7.8.2-rev4<br>Open-Xchange EAS 7.8.2-rev4<br>Open-Xchange OXUpdater 7.8.2-rev4 (6.18.33)<br>Open-Xchange Drive Restricted 7.8.2-rev4<br>Open-Xchange Documents 7.8.2-rev4<br>Open-Xchange Documents Frontend 7.8.2-rev4<br>Open-Xchange Readerengine 7.8.2-rev3 (5.0.7)<br>Open-Xchange Documentconverter 7.8.2-rev4<br>Open-Xchange Documentconverter API 7.8.2-rev4<br>Open-Xchange Connector for Microsoft Outlook 7.2.23<br>Open-Xchange Notifier 1.0.6<br>Open-Xchange Guard 2.4.2-rev4<br />
|-<br />
|2016-07-14<br />
|Open-Xchange Drive for Windows<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Drive for Windows v2.0.2<br />
|-<br />
|2016-07-18<br />
|OX App Suite v7.8.0 and OX 6 Middleware v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev35<br>Open-Xchange App Suite Frontend v7.8.0-rev28<br />
|-<br />
|2016-07-18<br />
|OX App Suite v7.8.1 and OX 6 Middleware v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev17<br>Open-Xchange App Suite Frontend v7.8.1-rev15<br>Open-Xchange EAS v7.8.1-rev9<br />
|-<br />
|2016-07-21<br />
|OX Guard v2.4.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.4.0-rev10<br />
|-<br />
|2016-07-21<br />
|Connector for Microsoft Outlook<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Connector for Microsoft Outlook v7.2.23<br>Open-Xchange Updater Backend Package v7.8.1-rev10<br />
|-<br />
|2016-08-01<br />
|OX App Suite v7.6.2 and OX 6 Middleware v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev58<br>Open-Xchange App Suite frontend v7.6.2-rev46<br />
|-<br />
|2016-08-01<br />
|OX App Suite v7.6.3 and OX 6 Middleware v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev14<br>Open-Xchange App Suite frontend v7.6.3-rev15<br />
|-<br />
|2016-08-01<br />
|OX App Suite v7.8.0 and OX 6 Middleware v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev36<br>Open-Xchange App Suite frontend v7.8.0-rev29<br />
|-<br />
|2016-08-01<br />
|OX App Suite v7.8.1 and OX 6 Middleware v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev18<br>Open-Xchange App Suite frontend v7.8.1-rev16<br />
|-<br />
|2016-08-01<br />
|OX App Suite v7.8.2 and OX 6 Middleware v7.8.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.2-rev5<br>Open-Xchange App Suite frontend v7.8.2-rev5<br />
|-<br />
|2016-08-09<br />
|OX Mail app<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|OX Mail app v1.4.0<br />
|-<br />
|2016-08-15<br />
|OX App Suite v7.8.1 and OX 6 Middleware v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev19<br>Open-Xchange App Suite frontend v7.8.1-rev17<br />
|-<br />
|2016-08-15<br />
|OX App Suite v7.8.2 and OX 6 Middleware v7.8.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.2-rev6<br>Open-Xchange App Suite frontend v7.8.2-rev6<br />
|-<br />
|2016-08-15<br />
|OX App Suite v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite frontend v7.8.1-rev18<br />
|-<br />
|2016-08-15<br />
|OX App Suite v7.8.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite frontend v7.8.2-rev7<br />
|-<br />
|2016-08-18<br />
|OX Guard v2.4.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.4.0-rev11<br />
|-<br />
|2016-08-18<br />
|OX Guard v2.4.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.4.2-rev5<br />
|-<br />
|2016-08-22<br />
|Open-Xchange releases OX App Suite v7.8.2, OX Documents v7.8.2, OX Guard v2.4.2 and eM Client for App Suite for Univention Corporate Server v4.1<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange Middleware 7.8.2-rev4<br>Open-Xchange OX6 Middleware 7.8.2-rev4<br>Open-Xchange App Suite frontend 7.8.2-rev4<br>Open-Xchange OX6 frontend 6.22.12-rev4<br>Open-Xchange USM 7.8.2-rev4<br>Open-Xchange EAS 7.8.2-rev4<br>Open-Xchange OXUpdater 7.8.2-rev4 (6.18.33)<br>Open-Xchange Drive Restricted 7.8.2-rev4<br>Open-Xchange Documents 7.8.2-rev4<br>Open-Xchange Documents Frontend 7.8.2-rev4<br>Open-Xchange Readerengine 7.8.2-rev3 (5.0.7)<br>Open-Xchange Documentconverter 7.8.2-rev4<br>Open-Xchange Documentconverter API 7.8.2-rev4<br>Open-Xchange Connector for Microsoft Outlook 7.2.23<br>Open-Xchange Guard 2.4.2-rev4<br />
|-<br />
|2016-08-22<br />
|OX Messenger v1.4.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Messenger 1.4.1-rev5<br />
|-<br />
|2016-08-29<br />
|OX App Suite v7.6.2, OX 6 Middleware v7.6.2 and OX Documents v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev59<br>Open-Xchange App Suite frontend v7.6.2-rev47<br>Open-Xchange Office Web v7.6.2-rev16<br />
|-<br />
|2016-08-29<br />
|OX App Suite v7.6.3, OX 6 Middleware v7.6.3 and OX Documents v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev15<br>Open-Xchange App Suite frontend v7.6.3-rev16<br>Open-Xchange Office Web v7.6.3-rev4<br />
|-<br />
|2016-08-29<br />
|OX App Suite v7.8.0, OX 6 Middleware v7.8.0 and OX Documents v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev38<br>Open-Xchange App Suite frontend v7.8.0-rev30<br>Open-Xchange Office Web v7.8.0-rev10<br />
|-<br />
|2016-08-29<br />
|OX App Suite v7.8.1, OX 6 Middleware v7.8.1 and OX Documents v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev20<br>Open-Xchange App Suite frontend v7.8.1-rev19<br>Open-Xchange Office Web v7.8.1-rev9<br />
|-<br />
|2016-08-29<br />
|OX App Suite v7.8.2, OX 6 Middleware v7.8.2 and OX Documents v7.8.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.2-rev8<br>Open-Xchange App Suite frontend v7.8.2-rev8<br>Open-Xchange Office Web v7.8.2-rev5<br>Open-Xchange Documentconverter API 7.8.2-rev5<br />
|-<br />
|2016-09-08<br />
|Dovecot Anti-Abuse Shield<br />
|[[File:check.gif]]<br />
|<br />
|<br />
|Open-Xchange Weakforced v1.0.0-rev3<br />
|-<br />
|2016-09-12<br />
|OX App Suite v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev21<br>Open-Xchange App Suite Frontend v7.8.1-rev20<br />
|-<br />
|2016-09-12<br />
|OX App Suite v7.8.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.2-rev9<br>Open-Xchange App Suite Frontend v7.8.2-rev9<br />
|-<br />
|2016-09-20<br />
|OX Guard v2.4.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.4.2-rev6<br />
|-<br />
|2016-09-26<br />
|OX App Suite v7.6.2, OX 6 Middleware v7.6.2 and OX Documents v7.6.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.2-rev60<br>Open-Xchange App Suite Frontend v7.6.2-rev48<br>Open-Xchange Documents Frontend v7.6.2-rev17<br />
|-<br />
|2016-09-26<br />
|OX App Suite v7.6.3, OX 6 Middleware v7.6.3 and OX Documents v7.6.3<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.6.3-rev17<br>Open-Xchange App Suite Frontend v7.6.3-rev18<br>Open-Xchange Documents Frontend v7.6.3-rev5<br />
|-<br />
|2016-09-26<br />
|OX App Suite v7.8.0, OX 6 Middleware v7.8.0 and OX Documents v7.8.0<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.0-rev39<br>Open-Xchange App Suite Frontend v7.8.0-rev31<br>Open-Xchange Documents Frontend v7.8.0-rev11<br />
|-<br />
|2016-09-26<br />
|OX App Suite v7.8.1, OX 6 Middleware v7.8.1 and OX Documents v7.8.1<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev22<br>Open-Xchange App Suite Frontend v7.8.1-rev21<br>Open-Xchange Documents Frontend v7.8.1-rev10<br>Open-Xchange USM v7.8.1-rev9<br />
|-<br />
|2016-09-26<br />
|OX App Suite v7.8.2, OX 6 Middleware v7.8.2 and OX Documents v7.8.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.2-rev11<br>Open-Xchange App Suite Frontend v7.8.2-rev11<br>Open-Xchange Documents Frontend 7.8.2-rev6<br>Open-Xchange Documentconverter 7.8.2-rev5<br>Open-Xchange USM v7.8.2-rev5<br />
|-<br />
|2016-10-06<br />
|OX Drive app v2.2.0 for Windows<br />
|<br />
|[[File:check.gif]]<br />
|<br />
|Open-Xchange OX Drive for Windows v2.2.0<br />
|-<br />
|2016-10-10<br />
|OX Guard v2.4.2<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Guard v2.4.2-rev7<br />
|-<br />
|2016-10-10<br />
|OX App Suite v7.8.1, OX 6 Backend v7.8.1 and Connector for Business Mobility<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.1-rev23<br>Open-Xchange USM v7.8.1-rev10<br>Open-Xchange EAS v7.8.1-rev10<br />
|-<br />
|2016-10-10<br />
|OX App Suite v7.8.2, OX 6 Backend v7.8.2 and Connector for Business Mobility<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange App Suite / OX 6 Middleware (backend) v7.8.2-rev12<br>Open-Xchange App Suite Frontend v7.8.2-rev13<br>Open-Xchange USM v7.8.2-rev6<br>Open-Xchange EAS v7.8.2-rev5<br />
|-<br />
|2016-10-13<br />
|Connector for Microsoft Outlook<br />
|<br />
|<br />
|[[File:check.gif]]<br />
|Open-Xchange Connector for Microsoft Outlook v7.2.24<br>Open-Xchange Updater Backend Package v7.8.1-rev11<br>Open-Xchange Updater Backend Package v7.8.2-rev5<br />
|}<br />
<br />
== Current Product Version Matrix ==<br />
<br />
Open-Xchange products comprise of two major components: Front End and Back End. Each of these components can be rev’ed independently of each other. The following table shows the most recent combinations of Front End version and Back End version that make up a complete product version.<br />
<br />
=== OX App Suite ===<br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |Version <br />
!align="left" |Backend <br />
!align="left" |Frontend<br />
|-<br />
|v7.8.2<br />
|v7.8.2-rev12<br />
|v7.8.2-rev13<br />
|-<br />
|v7.8.1<br />
|v7.8.1-rev23<br />
|v7.8.1-rev21<br />
|-<br />
|v7.8.0<br />
|v7.8.0-rev39<br />
|v7.8.0-rev31<br />
|-<br />
|v7.6.3<br />
|v7.6.3-rev17<br />
|v7.6.3-rev18<br />
|-<br />
|}<br />
<br />
=== Open-Xchange Server 6 ===<br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |Version<br />
!align="left" |Backend <br />
!align="left" |Frontend<br />
|-<br />
|v7.8.2 / v6.22.12<br />
|v7.8.2-rev12<br />
|v6.22.12-rev4<br />
|-<br />
|v7.8.1 / v6.22.11<br />
|v7.8.1-rev23<br />
|v6.22.11-rev8<br />
|-<br />
|v7.8.0 / v6.22.10<br />
|v7.8.0-rev39<br />
|v6.22.10-rev8<br />
|-<br />
|v7.6.3<br />
|v7.6.3-rev17<br />
|v6.22.9-rev16<br />
|-<br />
|}<br />
<br />
==Please Note - Additional Information ==<br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |Product-, Release- and Component Name<br />
!align="left" |Additional Information<br />
|-<br />
|File Storage Integrations<br />
|OX App Suite has the possibility to let users integrate their cloud storage accounts of 3rd party services with the OX Drive module of the web UI: [[AppSuite:Filestorages|File Storages]]. Access to these services is intentionally limited to web UI and will not be part of the OX Drive apps or the existing WebDAV interface.<br />
|-<br />
|LinkedIn Integration<br />
|Regarding the integration between OX App Suite and LinkedIn, we would like to notify you about an upcoming LinkedIn API change, which is used by the App Suite app server. <br />
<br />
We were informed by LinkedIn this week that LinkedIn will restrict access to parts of their currently available API for all existing users and partners by May 15th. LinkedIn will only allow access to the full API, if you sign up for the LinkedIn partner program. Read More: [https://forum.open-xchange.com/showthread.php?9261 Open-Xchange Forum]<br />
|-<br />
|Facebook Integration<br />
|Facebook has introduced a new API Permission called “read_stream”, which allows clients of their API to retrieve the Facebook stream of a user. This data was used in the OX App Suite Portal widget to give users instant access to their Facebook data without leaving App Suite. The issue with this new API permission is that Facebook only grants it to 3rd party applications which do not run on the following platforms (All platforms where Facebook already is present): Web, TV, iOS, Android, In-Car. Read More: [https://forum.open-xchange.com/showthread.php?9403 Open-Xchange Forum]<br />
|-<br />
|T-Online Integration<br />
|Regarding the integration between App Suite and the social network T-Online, we would like to notify you about an upcoming T-Online change, which is used by the App Suite app server. As a result of the change from a clickable HTML page to a single-page-javascript application, the Open-Xchange App Suite Integration for T-Online will stop working and removed.<br />
|}<br />
<br />
==Maintenance expires==<br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |Product-, Release- and Component Name<br />
!align="left" |Maintance expires<br />
|-<br />
|In accordance with the supported platform policy, Open-Xchange announces the discontinuation of support for Suse Linux Enterprise Server 11 (SLES 11) and Debian Wheezy with an upcoming release of OX App Suite, planned for Q4 2016. We encourage administrators to update to the latest operating system version, Suse Linux Enterprise Server 12 (SLES 12) and Debian Jessie. For details of all supported platforms and databases please refer to the requirements page at: http://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Server_Platforms <br />
|Planned in Q4 2016<br />
|-<br />
|In accordance with the supported platform policy, Open-Xchange announces the discontinuation of support for Apple iOS 8 for mobile and tablet devices, with the next minor release of OX App Suite, v7.8.3, planned for Q4 2016. <br />
|Planned in Q4 2016<br />
|-<br />
|In accordance with the supported platform policy, Open-Xchange announces the discontinuation of support for Apple Mac OS X 10.10 (Yosemite), with the next minor release of OX App Suite, v7.8.3, planned for Q4 2016. <br />
|Planned in Q4 2016<br />
|}<br />
<br />
==Maintenance expired (Archive)==<br />
<br />
{| border="1" cellpadding="3" cellspacing="0"<br />
!align="left" |Product-, Release- and Component Name<br />
!align="left" |Maintance expired<br />
|-<br />
|In accordance with the supported platform policy, Open-Xchange announces the discontinuation of Internet Explorer 10 support for OX App Suite web frontend. This comes in with the release of OX App Suite v7.8.1. For details of all supported browsers please refer to the requirements page at:<br />
http://oxpedia.org/wiki/index.php?title=AppSuite:OX_System_Requirements#Desktop_Browser_.28Minimum_display_resolution:_1024_x_768.29<br />
|Since OX App Suite v7.8.1: 2016-03-31<br />
|-<br />
|Open-Xchange will discontinue support for Apple iOS 7 with the next major release of OX App Suite v7.8.0<br />
|Since OX App Suite v7.8.0: 2015-10-07<br />
|-<br />
|Open-Xchange will discontinue support for Debian Squeeze (Debian 6) with the next major release of OX App Suite v7.8.0. We encourage administrators to update to the latest operating system version of Debian.<br />
|Since OX App Suite v7.8.0: 2015-10-07<br />
|-<br />
|With the v7.8.0 release, Open-Xchange will discontinue support for the Random Token login method (sometimes also called Easy Login). Specifically, this means that the "login?action=redirect" call (see http://oxpedia.org/wiki/index.php?title=HTTP_API#Redirect) will be removed. Furthermore, the "com.openexchange.ajax.login.randomToken" setting will be removed from the "login.properties" file, and the "login?action=login" call will never contain the "random" token. We strongly encourage users of the Random Token login method to change their custom login implementations and use one of the supported methods.<br />
|Since OX App Suite v7.8.0: 2015-10-07<br />
|-<br />
|Open-Xchange discontinues support for Apple Mac OS X 10.8 Mountain Lion with the minor release of OX App Suite, v7.6.2: 2015-03-11<br />
|Since OX App Suite v7.6.2: 2015-03-16<br />
|-<br />
|Open-Xchange discontinues support for Apple iOS 6 with the minor release of OX App Suite, v7.6.2<br />
|Since OX App Suite v7.6.2: 2015-03-16<br />
|-<br />
|Open-Xchange discontinued support of all old Android stock browsers on mobile and tablet devices with the release of OX App Suite v7.6.1. OX App Suite is only supported on the new official stock browser, Chrome on Android.<br />
|Since OX App Suite v7.6.1: 2014-10-15<br />
|-<br />
|Support for AJP based communication between the HTTP server and the OX backend server. Open-Xchange already provides a new HTTP connector which is based on the Grizzly project. Download and configuration instructions are available at http://oxpedia.org/wiki/index.php?title=AppSuite:Grizzly<br />
|Since OX App Suite v7.6.0: 2014-06-25<br />
|-<br />
|Open-Xchange discontinued OX App Suite web frontend support for Internet Explorer 9 with the major release of OX App Suite v7.6.0.<br />
|Since OX App Suite v7.6.0: 2014-06-25<br />
|-<br />
|Open-Xchange discontinued Open-Xchange Server 6 and OX App Suite calendar and contact synchronization (CalDAV/CardDAV) support for Mac OS X 10.6 (Snow Leopard) and Mac OS X 10.7 (Lion) with the major release of OX App Suite v7.6.0.<br />
|Since OX App Suite v7.6.0: 2014-06-25<br />
|-<br />
|Open-Xchange discontinued Connector for Business Mobility support for Windows Mobile 6, 6.5, Symbian (Mail for Exchange 3.x), Apple iPhone iOS 5 and Blackberry with the major release of OX App Suite v7.6.0.<br />
|Since OX App Suite v7.6.0: 2014-06-25<br />
|-<br />
|With OX App Suite v7.4.2, the name of the “Files” app was changed to “Drive”. As part of our product strategy we developed clients for different desktop and mobile devices to provide improved file handling and synchronization.<br />
|Since OX App Suite v7.4.2: 2014-02-11<br />
|-<br />
|Debian 7 (Wheezy) was released by the Debian project on May 4th 2013. Both OX App Suite and Open-Xchange Server 6 support Debian 7 with OpenJDK 7 and MySQL 5.5 with this release of OX App Suite. Please note that the combination Debian 7 / OpenJDK 6 or Sun Java 6 will not be supported as a platform by Open-Xchange.<br />
|Since OX App Suite v7.4.0: 2013-09-26<br />
|-<br />
|Open-Xchange discontinued support for the currently available "showruntimestats" monitoring function (which fetches runtime information from the Java virtual machine and about the Open-Xchange Groupware backend). With OX App Suite v7.4.0, there is a new monitoring function using Jolokia for Open-Xchange. From v7.4.0 onwards, this is located inside the Open-Xchange Bundle and configured by jolokia.properties. Further information can be found at http://oxpedia.org/wiki/index.php?title=Jolokia<br />
|Since OX App Suite v7.4.0: 2013-09-26<br />
|-<br />
|Open-Xchange provided a new LDAP Contact Storage Integration Bundle. Open-Xchange discontinued support for the old bundle with OX App Suite v7.2.1. Further configuration information is available at the Open-Xchange Knowledgebase under: http://oxpedia.org/wiki/index.php?title=ContactStorageLDAP<br />
|Since OX App Suite v7.2.1: 2013-05-27<br />
|}<br />
<br />
== What version do I have installed ==<br />
<br />
Check [[UpdatingOXPackages#What_Service_Pack_do_I_have_installed.3F|this article]] to find out.<br />
<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Client_Onboarding&diff=22234AppSuite:Client Onboarding2016-07-26T14:28:34Z<p>Steffen.templin: /* Configuring actions */</p>
<hr />
<div><div class="title">Client Onboarding</div><br />
<br />
{{VersionFrom|7.8.1}}<br />
<br />
__TOC__<br />
<br />
= Configuration guide for Open-Xchange Client Onboarding =<br />
<br />
With Open-Xchange Server v7.8.1 a new module is added allowing users to integrate several different clients and devices with Open-Xchange; such as providing a link to a commercial App Store to install certain apps on mobile devices.<br />
<br />
By default, Open-Xchange ships with several built-in providers; thereof<br />
<br />
* CalDAV<br />
* CardDAV<br />
* OX Mail App<br />
* OX Drive App<br />
* Connector for Microsoft Outlook®<br />
* Sync App for Android<br />
* Microsoft ActiveSync<br />
* eM Client<br />
* Mail (IMAP/SMTP)<br />
* Generic Mobile App provider<br />
<br />
Those providers allow accessing and/or synchronizing with certain data held by Open-Xchange on a supported device.<br />
<br />
== Installation ==<br />
<br />
To install the Client Onboarding module, the package open-xchange-client-onboarding needs to be installed.<br />
<br />
Moreover the property <code>"com.openexchange.client.onboarding.enabled"</code>; in installed file <code>/opt/open-xchange/etc/client-onboarding.properties</code> needs to be set to <code>"true"</code> (default). So getting rid off the entire client on-boarding module simply requires setting the mentioned property to <code>"false"</code> (and executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool).<br />
<br />
== Onboarding scenarios ==<br />
<br />
The way to specify what and how a certain device is able to get “on-boarded” is mainly determined by so called scenarios. A scenario describes what gets deployed using which providers that contribute their onboarding possibilities and how it is made accessible to the client’s device.<br />
<br />
A scenario consists of the following configuration attributes/options<br />
<br />
* A unique scenario identifier<br />
* A flag determining if scenario is enabled or not. If set to 'false' the scenario will not be available, useful for testing/enabling the scenario later on<br />
* A scenario type, which is one of &quot;plist&quot;, &quot;manual&quot;, or &quot;link&quot;<br />
** &quot;plist&quot; for generating a PLIST configuration file for iOS and OSX devices,<br />
** &quot;manual&quot; for a description for the user for a manual set-up/configuration<br />
** &quot;link&quot; for a link/URL to either Apple App Store / Google Play Store or to downloadable executable<br />
* The &quot;link&quot; attribute, which is only considered it type is set to &quot;link&quot;. That attribute consists of the sub-attributes &quot;url&quot; and &quot;type&quot;.<br />
** &quot;url&quot; provides the actual link/URL to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. For specifying a property that provides the actual link, please use special &quot;property&quot; scheme; e.g. &quot;property://com.openexchange.client.onboarding.app.mylink&quot;<br />
** &quot;type&quot; indicates if &quot;url&quot; holds a link for either Apple App Store, Apple Mac Store or Google Play Store. Must only be specified in case &quot;url&quot; points either of those commercial stores. Supported values are &quot;appstore&quot;, &quot;macstore&quot; and &quot;playstore&quot;<br />
* The identifiers for the providers, which contribute to the scenario;<br /><br />
please check command-line tool <code>/opt/open-xchange/sbin/listonboardingproviders</code> to check, which ones are available<br />
* The identifiers for alternative scenarios. This is typically used to provide alternative manual setup possibility.<br />
* The comma-separated names of Font Awesome icons that are supposed to be displayed for the scenario<br /><br />
(only the ones from v4.4.0 are currently supported)<br />
* The translatable display name; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts<br />
* The translatable description; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts<br />
<br />
== Onboarding providers ==<br />
<br />
As described in the previous section, a scenario specifies what providers contribute to it. A provider represents a certain App or (synchronization) protocol that a device can install, download and/or communicate with.<br />
<br />
Moreover a provider specifies what Onboarding types are supported (&quot;plist&quot;, &quot;manual&quot;, and/or &quot;link&quot;). Hence, once a provider is chosen to contribute to a certain scenario, the supported on-boarding type needs to match the one of the scenario itself. E.g. a scenario, which indicates to be of type &quot;link&quot;, will always fail if the associated provider signals to support types &quot;plist&quot; and &quot;manual&quot;.<br />
<br />
To check what providers are available on your system, please execute the <code>/opt/open-xchange/sbin/listonboardingproviders</code> command-line tool, which outputs something like:<br />
<br />
[[File:onboarding_1.png]]<br />
<br />
Each provider might require one or more capabilities/permissions to be available for the requesting user. If capabilities/permissions are not satisfied, the associated scenario cannot be applied, but will be displayed to the user for upsell opportunities.<br />
<br />
=== Generic Onboarding provider for Apps ===<br />
<br />
Identifier: <code>app</code><br />
<br />
The generic onboarding provider for apps allows specifying custom scenarios of type &quot;link&quot; for arbitrary links/URLs pointing to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. The link can be set directly or via a property.<br />
<br />
This provider requires no capability/permission.<br />
<br />
An exemplary section in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file might look like (check &quot;Configuring Onboarding scenarios&quot; chapter for more details):<br />
<br />
[[File:onboarding_2.png]]<br />
<br />
=== CalDAV/CardDAV ===<br />
<br />
Identifiers: <code>caldav</code> &amp; <code>carddav</code><br />
<br />
In order for a scenario (having CalDAV/CardDAV in its provider listing) to be executable by a user, the &quot;caldav&quot; capability and &quot;carddav&quot; capability respectively are required.<br />
<br />
Moreover, the appropriate *DAV end-points are supposed to be configured through property <code>com.openexchange.client.onboarding.caldav.url</code> in <code>client-onboarding-caldav.properties</code> file and property <code>com.openexchange.client.onboarding.carddav.url</code> in <code>client-onboarding-carddav.properties</code> file.<br />
<br />
=== Drive/Mail Apps ===<br />
<br />
Identifiers: <code>driveapp</code> &amp; <code>mailapp</code><br />
<br />
Open-Xchange ships with built-in providers for Drive App and Mail App. The Drive-associated providers do require the &quot;drive&quot; capability and the Mail App requires the &quot;mobile_mail_app&quot; one.<br />
<br />
The appropriate links to the apps in the corresponding stores are configured in associated .properties files:<br />
<br />
* <code>client-onboarding-driveapp.properties</code><br />
* <code>client-onboarding-mailapp.properties</code><br />
<br />
By default the links to the official apps are set, but may be changed to ones for branded versions.<br />
<br />
=== Drive Windows Client ===<br />
<br />
Identifier: <code>drivewindowsclient</code><br />
<br />
The provider for the windows Drive Client. Requires the &quot;drive&quot; capability, but has no configuration options. However, this provider requires the &quot;open-xchange-drive-client-windows&quot; and the orderly configured binaries (e.g. through installing appropriate package according to the brand).<br />
<br />
Please check [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive#OX_Drive_for_Windows ''this''] documentation for more details.<br />
<br />
<!-- === eM Client ===<br />
<br />
Identifier: <code>emclient</code><br />
<br />
The provider for the eM Client needs the &quot;emclient&quot; capability.<br />
<br />
Allows to configure the URL pointing to the executable file through <code>com.openexchange.client.onboarding.emclient.url</code> in file 'client-onboarding-emclient.properties' file.<br />
<br />
=== Sync App ===<br />
<br />
Identifier: <code>syncapp</code><br />
<br />
The provider for the Sync App for Android. Requires &quot;caldav&quot; and &quot;carddav&quot; capabilities.<br />
<br />
The link to Google Play Store is specified via property <code>com.openexchange.client.onboarding.syncapp.store.google.playstore</code> in <code>client-onboarding-syncapp.properties</code> file. --><br />
<br />
=== Mail (IMAP/SMTP) ===<br />
<br />
Identifier: <code>mail</code><br />
<br />
The provider for deploying the IMAP/STMP account on target device using native/stock mail app. All IMAP/SMTP related settings are settable in file 'client-onboarding-mail.properties'.<br />
<br />
=== Microsoft ActiveSync (EAS) ===<br />
<br />
Identifier: <code>eas</code><br />
<br />
Configures the ActiveSync account on target device. Allows specifying the EAS end-point through <code>com.openexchange.client.onboarding.eas.url</code> property in 'client-onboarding-eas.properties'.<br />
<br />
=== OX Updater ===<br />
<br />
Identifier: <code>oxupdater</code><br />
<br />
The provider offering the download for the OX Client Updater ([http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''http:''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''//oxpedia''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''org/wiki/index''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''php''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''?''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''title=AppSuite''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater '':''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''Open-Xchange_Updater'']). The provider is available as soon as the according package is installed and at least one product can be installed/updated via it by the user. A pre-configured scenario 'oxupdaterinstall' is already contained in <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code>.<br />
<br />
== Configuring Onboarding scenarios ==<br />
<br />
Onboarding scenarios are configured through the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Each scenario starts with its own &quot;section&quot; in that YAML file by typing its unique identifier. All further attributes as outlined in chapter &quot;Onboarding scenarios&quot; are nested below that identifier.<br />
<br />
=== Easily enabling/disabling scenarios ===<br />
<br />
By default, Open-Xchange ships with a set of pre-defined scenarios that might apply to the most common installations. Each scenario can easily be enabled/disabled through its &quot;enabled&quot; Boolean attribute in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool applies the changes without the need for restart.<br />
<br />
=== Translatable strings ===<br />
<br />
Those attributes ending with &quot;_t10e&quot; refer to localizable strings and are placed into &quot;client-onboarding-scenarios.pot&quot; file. Once such attributes ending with &quot;_t10e&quot; are changed/customized and/or added, the appropriate &quot;client-onboarding-scenarios.pot&quot; file needs to be re-created in order to get translated. For generating that &quot;client-onboarding-scenarios.pot&quot; file, please execute the /opt/open-xchange/sbin/parsei18nyaml command-line tool. That .pot file needs then be turned to the .po files for the individual languages.<br />
<br />
Thus changing any of the attributes ending with &quot;_t10e&quot; requires (provided that appropriate .po files are available in <code>/opt/open-xchange/i18n</code> directory) either a restart or executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool together with stop/start of the &quot;com.openexchange.i18n&quot; bundle.<br />
<br />
=== Scenario scope ===<br />
<br />
While the previously mentioned &quot;enabled&quot; attribute offers some kind of generic on/off switch, the properties outlined in this section allow defining the scope for a scenario. Scope in terms of<br />
<br />
* For what devices (from the set of those specified by providers) is that scenario available and<br />
* For which users is it available<br />
<br />
As explained above, each scenario specifies one or more type-compatible providers associated with it. In turn, each provider determines to which devices the scenario applies. In order to further control, which device and which users are allowed to access a certain scenario, there are appropriate options available in file <code>/opt/open-xchange/etc/client-onboarding.properties</code>. Every option is fully [http://oxpedia.org/wiki/index.php?title=ConfigCascade ''config-cascade''] aware and therefore can be controlled on a global, per context set, per context and per user basis.<br />
<br />
Thus, to make a scenario available for certain devices (as dictated by scenario’s providers) and for users as well, the scenario identifier needs to be added to the appropriate properties ending with &quot;.scenarios&quot; (for devices) and added to the &quot;com.openexchange.client.onboarding.enabledScenarios&quot; property (for user) as well:<br />
<br />
<blockquote>com.openexchange.client.onboarding.apple.mac.scenarios<br /><br />
com.openexchange.client.onboarding.apple.ipad.scenarios<br /><br />
com.openexchange.client.onboarding.apple.iphone.scenarios<br /><br />
com.openexchange.client.onboarding.android.tablet.scenarios<br /><br />
com.openexchange.client.onboarding.android.phone.scenarios<br /><br />
com.openexchange.client.onboarding.windows.desktop.scenarios<br />
<br />
com.openexchange.client.onboarding.enabledScenarios<br />
</blockquote><br />
Once a scenario is made accessible through configuration it is visible to users trying to perform a client onboarding using one of associated devices. However, whether a user is effectively allowed to execute that scenario is determined by the required capabilities of the denoted providers; if not allowed it gets displayed as an upsell opportunity.<br />
<br />
=== Configuring actions ===<br />
<br />
The type for a scenario determines what actions are associated with it to &quot;''transport''&quot; the onboarding information to the client. The types &quot;manual&quot; and &quot;link&quot; only show static information like displaying a link. In contrast the type &quot;plist&quot; allows several actions to transport the configuration profile onto the client. Thereof<br />
<br />
* E-Mail<br />
* SMS<br />
<br />
In order to utilize the &quot;E-Mail&quot; action, a special transport must be configured for system-composed E-Mails [http://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode#Share_Notifications ''as it is for using the sharing functionality'']. This transport is configured in noreply.properties. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.<br />
<br />
Using the SMS action requires an according implementation being available. OX App Suite comes with an optional sipgate implementation. Please check [http://oxpedia.org/wiki/index.php?title=AppSuite:SMS_Sipgate ''this documentation''] how to setup App Suite accordingly.<br />
<br />
==== Implementing your own SMS gateway ====<br />
<br />
To use an SMS gateway other than sipgate, you can provide your own implementation. Therefore the Java interface <code>com.openexchange.sms.SMSServiceSPI</code> needs to be implemented and published as an OSGi service. For parsing phone numbers provided by users <code>com.openexchange.sms.PhoneNumberParserService</code> can be used. That one is also available as an OSGi service and can be tracked accordingly. You can have a look at bundle <code>com.openexchange.sms.sipgate</code> as implementation reference.<br />
<br />
'''Important:''' You must not install the <code>open-xchange-sms-sipgate</code> package if you provide your own implementation.<br />
<br />
==== PLIST-signing ====<br />
Scenarios of type &quot;plist&quot; require having PLIST-signing enabled. Otherwise the device will show a warning when importing a received PLIST configuration profile. Please follow the instructions as outlined in [http://oxpedia.org/wiki/index.php?title=AppSuite:PList_signing ''this article''] how to enable and configure signing for PLIST files.<br />
<br />
== Adding custom scenarios ==<br />
<br />
The first thing to do, is to add an appropriate scenario configuration to the 'client-onboarding-scenarios.yml' file; e.g.<br />
<br />
<blockquote>mygoogleapp:<br /><br />
enabled: true<br /><br />
type: link<br /><br />
link:<br /><br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br /><br />
type: playstore<br /><br />
providers: [app]<br /><br />
alternatives: []<br /><br />
icon: fa-cloud<br /><br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br /><br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;<br />
</blockquote><br />
The next step is to make that scenario accessible through adapting 'client-onboarding.properties' file. Hence, the scenario identifier needs to be added to the devices, to which it applies (Android devices in this case):<br />
<br />
<blockquote>com.openexchange.client.onboarding.android.tablet.scenarios=..., mygoogleapp<br /><br />
com.openexchange.client.onboarding.android.phone.scenarios=..., mygoogleapp<br />
</blockquote><br />
Furthermore, that scenario needs to be made accessible to users as well:<br />
<br />
<blockquote>com.openexchange.client.onboarding.enabledScenarios=..., mygoogleapp<br />
</blockquote><br />
At last, a .pot file is supposed to be generated from the translatable strings using /opt/open-xchange/sbin/parsei18nyaml command-line tool to yield the .po files for the individual languages.<br />
<br />
Provided that target users do hold appropriate capabilities, they are allowed to execute that scenario. In the example above the &quot;app&quot; provider is specified, which does no require any capabilities. Hence, that scenario is available.<br />
<br />
== HowTos ==<br />
<br />
=== How can I quickly setup a default/test configuration ? ===<br />
<br />
# Install open-xchange-client-onboarding package<br />
# Edit <code>/opt/open-xchange/etc/client-onboarding.properties</code> and set <code>com.openexchange.client.onboarding.enabled</code> to <code>true</code> <br />
# Edit <code>noreply.properties</code> to enable autoconfig sending via email. PS: Have a fully working smtp login available like “noreply@yourdomain.tld”<br />
# Edit client-onboarding-scenarios.yml and set “enable” for : “driveappinstall” , “davsync” “davmanual” “mailsync” “mailmanual” to <code>true</code> <br />
# Now set the correct caldav/carddav server FQDNs in the corresponding files for your setup<br />
#*<code>client-onboarding-caldav.properties</code> <br />
#*<code>client-onboarding-carddav.properties</code><br />
# Restart OX process<br />
# Login to AppSuite. Click on Settings - Connect your device<br />
# Verify that you have following onboarding options available: <br />
#* windows -> imap/smtp details<br />
#* android/fon+tablet -> imap/smtp details<br />
#* android/fon+tablet -> drive app <br />
#* apple -> iphone -> imap/smtp config button<br />
#* apple -> iphone -> imap/smtp details for experts<br />
#* apple -> iphone -> calendar/addressbok -> config button<br />
#* apple -> iphone -> calendar/addressbok -> details for dav setup<br />
#* apple -> iphone -> drive app<br />
#* apple -> ipad -> imap/smtp config send email<br />
#* apple -> ipad -> imap/smtp config button<br />
#* apple -> ipad -> imap/smtp details for experts<br />
#* apple -> ipad -> calendar/addressbook config send email<br />
#* apple -> ipad -> calendar/addressbook config button<br />
#* apple -> ipad -> calendar/addressbook details for experts<br />
#* apple -> ipad -> drive app<br />
<br />
=== How can I quickly disable a certain scenario ===<br />
<br />
Simply enter the 'client-onboarding-scenarios.yml' file and go to the section specifying the target scenario. Switch the 'enabled' flag to &quot;false&quot; and execute /opt/open-xchange/sbin/reloadconfiguration command-line tool.<br />
<br />
E.g. to disable the OX Drive App:<br />
<br />
[[File:onboarding_3.png]]<br />
<br />
=== How can I disable the outdated ui parts like 'Downloads'? ===<br />
<br />
The wizard replaces and extends the functionality of the old Download Section in settings and the corresponding widgets. We recommend to disable these outdated parts:<br />
# widget: get ox drive<br />
# widget: update<br />
# settings entry: downloads<br />
<br />
'''Remove settings section 'Downloads' '''<br />
<br />
Edit ''/opt/open-xchange/etc/settings/appsuite.properties'' and add or change the value to true:<br />
* ''io.ox/core//settings/downloadsDisabled''<br />
<br />
'''Remove widgets'''<br />
<br />
To remove the both related portal widget/tiles please refer to the<br />
[[AppSuite:Configuring_portal_plugins#Disabling_a_tile_completely | portal plugins wiki page ]]<br />
<br />
* ''io.ox/portal/widget/oxdriveclients''<br />
* ''io.ox/portal/widget/updater''<br />
<br />
=== How can I add my own App? ===<br />
<br />
Provided that the App is accessible by a link (pointing to a commercial App Store or to a downloadable executable/installer), the generic &quot;app&quot; is the suitable provider to choose.<br />
<br />
Hence, an appropriate section is supposed to be added to the 'client-onboarding-scenarios.yml' file having a unique name and &quot;provider&quot; attribute set to &quot;[app]&quot;:<br />
<br />
<blockquote>mygoogleapp:<br /><br />
enabled: true<br /><br />
type: link<br /><br />
link:<br /><br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br /><br />
type: playstore<br /><br />
providers: [app]<br /><br />
alternatives: []<br /><br />
icon: fa-cloud<br /><br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br /><br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;<br />
</blockquote><br />
The attribute &quot;type&quot; needs to be set to &quot;link&quot;.<br />
<br />
The attribute &quot;link&quot; should be configured with:<br />
<br />
* &quot;url&quot; sub-attribute containing the actual link pointing to the URL location<br />
* &quot;type&quot; sub-attribute specifying of what type that link is: either &quot;appstore&quot;, &quot;macappstore&quot;, &quot;playstore&quot; or &quot;common&quot;.<br /><br />
The type &quot;common&quot; is supposed to be used for links that do not point to a commercial App Store, but to a downloadable executable/installer file.<br />
<br />
The &quot;icon&quot; attribute is supposed to contain a comma-separated list of Font Awesome icons (only the ones from v4.4.0 are currently supported) that represent the App; e.g.<br />
<br />
* &quot;fa-cloud&quot; for Drive/file-related nature<br />
* &quot;fa-calendar, fa-users&quot; for Calendar and Address Book synchronization<br />
* &quot;fa-envelope-o&quot; for Mail nature<br />
<br />
Next, the translatable display name and description should be set through setting the attributes &quot;displayName_t10e&quot; and &quot;description_t10e&quot;. As described previously, executing the /opt/open-xchange/sbin/parsei18nyaml command-line tool yields an appropriate .pot file, which can then be used for generating the individual .po file for the different translations.<br />
<br />
Finally, the 'client-onboarding.properties' file needs to be modified to specify the &quot;scope&quot; for that new scenario. Add the scenario’s unique name to the appropriate device properties and add it to &quot;com.openexchange.client.onboarding.enabledScenarios&quot; property as well.<br />
<br />
After executing /opt/open-xchange/sbin/reloadconfiguration command-line tool the new client onboarding scenario is available for the selected users/devices.<br />
<br />
=== How can I upsell my own app? ===<br />
<br />
Having the same prerequisites/steps as for &quot;How can I add my own App?&quot; the scenario description in the 'client-onboarding-scenarios.yml' file simply needs to be extended by the desired capabilities, which are supposed to be used for managing the upsell.<br />
<br />
Example<br />
<br />
<blockquote>mygoogleapp:<br /><br />
enabled: true<br /><br />
type: link<br /><br />
link:<br /><br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br /><br />
type: playstore<br /><br />
'''capabilities: &quot;mygoogleapp_capability&quot;'''<br /><br />
providers: [app]<br /><br />
alternatives: []<br /><br />
icon: fa-cloud<br /><br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br /><br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;<br />
</blockquote><br />
The special &quot;capabilities&quot; attribute is only supported for scenarios of type &quot;link&quot; with the special &quot;app&quot; provider.<br />
<br />
With such a &quot;capabilities&quot; attribute only users, which have the &quot;mygoogleapp_capability&quot; capability are allowed to get the link. For those who don’t, the upsell opportunity will be displayed; e.g.<br />
<br />
<blockquote>[[File:onboarding_4.png]]<br />
</blockquote></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Client_Onboarding&diff=21902AppSuite:Client Onboarding2016-05-11T07:33:56Z<p>Steffen.templin: /* How can I disable the outdated ui parts like 'Downloads'? */</p>
<hr />
<div><div class="title">Client Onboarding</div><br />
<br />
{{VersionFrom|7.8.1}}<br />
<br />
__TOC__<br />
<br />
= Configuration guide for Open-Xchange Client Onboarding =<br />
<br />
With Open-Xchange Server v7.8.1 a new module is added allowing users to integrate several different clients and devices with Open-Xchange; such as providing a link to a commercial App Store to install certain apps on mobile devices.<br />
<br />
By default, Open-Xchange ships with several built-in providers; thereof<br />
<br />
* CalDAV<br />
* CardDAV<br />
* OX Mail App<br />
* OX Drive App<br />
* Connector for Microsoft Outlook®<br />
* Sync App for Android<br />
* Microsoft ActiveSync<br />
* eM Client<br />
* Mail (IMAP/SMTP)<br />
* Generic Mobile App provider<br />
<br />
Those providers allow accessing and/or synchronizing with certain data held by Open-Xchange on a supported device.<br />
<br />
== Installation ==<br />
<br />
To install the Client Onboarding module, the package open-xchange-client-onboarding needs to be installed.<br />
<br />
Moreover the property <code>"com.openexchange.client.onboarding.enabled"</code>; in installed file <code>/opt/open-xchange/etc/client-onboarding.properties</code> needs to be set to <code>"true"</code> (default). So getting rid off the entire client on-boarding module simply requires setting the mentioned property to <code>"false"</code> (and executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool).<br />
<br />
== Onboarding scenarios ==<br />
<br />
The way to specify what and how a certain device is able to get “on-boarded” is mainly determined by so called scenarios. A scenario describes what gets deployed using which providers that contribute their onboarding possibilities and how it is made accessible to the client’s device.<br />
<br />
A scenario consists of the following configuration attributes/options<br />
<br />
* A unique scenario identifier<br />
* A flag determining if scenario is enabled or not. If set to 'false' the scenario will not be available, useful for testing/enabling the scenario later on<br />
* A scenario type, which is one of &quot;plist&quot;, &quot;manual&quot;, or &quot;link&quot;<br />
** &quot;plist&quot; for generating a PLIST configuration file for iOS and OSX devices,<br />
** &quot;manual&quot; for a description for the user for a manual set-up/configuration<br />
** &quot;link&quot; for a link/URL to either Apple App Store / Google Play Store or to downloadable executable<br />
* The &quot;link&quot; attribute, which is only considered it type is set to &quot;link&quot;. That attribute consists of the sub-attributes &quot;url&quot; and &quot;type&quot;.<br />
** &quot;url&quot; provides the actual link/URL to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. For specifying a property that provides the actual link, please use special &quot;property&quot; scheme; e.g. &quot;property://com.openexchange.client.onboarding.app.mylink&quot;<br />
** &quot;type&quot; indicates if &quot;url&quot; holds a link for either Apple App Store, Apple Mac Store or Google Play Store. Must only be specified in case &quot;url&quot; points either of those commercial stores. Supported values are &quot;appstore&quot;, &quot;macstore&quot; and &quot;playstore&quot;<br />
* The identifiers for the providers, which contribute to the scenario;<br /><br />
please check command-line tool <code>/opt/open-xchange/sbin/listonboardingproviders</code> to check, which ones are available<br />
* The identifiers for alternative scenarios. This is typically used to provide alternative manual setup possibility.<br />
* The comma-separated names of Font Awesome icons that are supposed to be displayed for the scenario<br /><br />
(only the ones from v4.4.0 are currently supported)<br />
* The translatable display name; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts<br />
* The translatable description; check <code>/opt/open-xchange/sbin/parsei18nyaml</code> command-line tool to generate a .pot file from translatable texts<br />
<br />
== Onboarding providers ==<br />
<br />
As described in the previous section, a scenario specifies what providers contribute to it. A provider represents a certain App or (synchronization) protocol that a device can install, download and/or communicate with.<br />
<br />
Moreover a provider specifies what Onboarding types are supported (&quot;plist&quot;, &quot;manual&quot;, and/or &quot;link&quot;). Hence, once a provider is chosen to contribute to a certain scenario, the supported on-boarding type needs to match the one of the scenario itself. E.g. a scenario, which indicates to be of type &quot;link&quot;, will always fail if the associated provider signals to support types &quot;plist&quot; and &quot;manual&quot;.<br />
<br />
To check what providers are available on your system, please execute the <code>/opt/open-xchange/sbin/listonboardingproviders</code> command-line tool, which outputs something like:<br />
<br />
[[File:onboarding_1.png]]<br />
<br />
Each provider might require one or more capabilities/permissions to be available for the requesting user. If capabilities/permissions are not satisfied, the associated scenario cannot be applied, but will be displayed to the user for upsell opportunities.<br />
<br />
=== Generic Onboarding provider for Apps ===<br />
<br />
Identifier: <code>app</code><br />
<br />
The generic onboarding provider for apps allows specifying custom scenarios of type &quot;link&quot; for arbitrary links/URLs pointing to Apple App Store, Apple Mac Store Google Play Store or to downloadable executable. The link can be set directly or via a property.<br />
<br />
This provider requires no capability/permission.<br />
<br />
An exemplary section in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file might look like (check &quot;Configuring Onboarding scenarios&quot; chapter for more details):<br />
<br />
[[File:onboarding_2.png]]<br />
<br />
=== CalDAV/CardDAV ===<br />
<br />
Identifiers: <code>caldav</code> &amp; <code>carddav</code><br />
<br />
In order for a scenario (having CalDAV/CardDAV in its provider listing) to be executable by a user, the &quot;caldav&quot; capability and &quot;carddav&quot; capability respectively are required.<br />
<br />
Moreover, the appropriate *DAV end-points are supposed to be configured through property <code>com.openexchange.client.onboarding.caldav.url</code> in <code>client-onboarding-caldav.properties</code> file and property <code>com.openexchange.client.onboarding.carddav.url</code> in <code>client-onboarding-carddav.properties</code> file.<br />
<br />
=== Drive/Mail Apps ===<br />
<br />
Identifiers: <code>driveapp</code> &amp; <code>mailapp</code><br />
<br />
Open-Xchange ships with built-in providers for Drive App and Mail App. The Drive-associated providers do require the &quot;drive&quot; capability and the Mail App requires the &quot;mobile_mail_app&quot; one.<br />
<br />
The appropriate links to the apps in the corresponding stores are configured in associated .properties files:<br />
<br />
* <code>client-onboarding-driveapp.properties</code><br />
* <code>client-onboarding-mailapp.properties</code><br />
<br />
By default the links to the official apps are set, but may be changed to ones for branded versions.<br />
<br />
=== Drive Windows Client ===<br />
<br />
Identifier: <code>drivewindowsclient</code><br />
<br />
The provider for the windows Drive Client. Requires the &quot;drive&quot; capability, but has no configuration options. However, this provider requires the &quot;open-xchange-drive-client-windows&quot; and the orderly configured binaries (e.g. through installing appropriate package according to the brand).<br />
<br />
Please check [https://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive#OX_Drive_for_Windows ''this''] documentation for more details.<br />
<br />
<!-- === eM Client ===<br />
<br />
Identifier: <code>emclient</code><br />
<br />
The provider for the eM Client needs the &quot;emclient&quot; capability.<br />
<br />
Allows to configure the URL pointing to the executable file through <code>com.openexchange.client.onboarding.emclient.url</code> in file 'client-onboarding-emclient.properties' file.<br />
<br />
=== Sync App ===<br />
<br />
Identifier: <code>syncapp</code><br />
<br />
The provider for the Sync App for Android. Requires &quot;caldav&quot; and &quot;carddav&quot; capabilities.<br />
<br />
The link to Google Play Store is specified via property <code>com.openexchange.client.onboarding.syncapp.store.google.playstore</code> in <code>client-onboarding-syncapp.properties</code> file. --><br />
<br />
=== Mail (IMAP/SMTP) ===<br />
<br />
Identifier: <code>mail</code><br />
<br />
The provider for deploying the IMAP/STMP account on target device using native/stock mail app. All IMAP/SMTP related settings are settable in file 'client-onboarding-mail.properties'.<br />
<br />
=== Microsoft ActiveSync (EAS) ===<br />
<br />
Identifier: <code>eas</code><br />
<br />
Configures the ActiveSync account on target device. Allows specifying the EAS end-point through <code>com.openexchange.client.onboarding.eas.url</code> property in 'client-onboarding-eas.properties'.<br />
<br />
=== OX Updater ===<br />
<br />
Identifier: <code>oxupdater</code><br />
<br />
The provider offering the download for the OX Client Updater ([http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''http:''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''//oxpedia''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''org/wiki/index''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''.''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''php''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''?''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''title=AppSuite''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater '':''][http://oxpedia.org/wiki/index.php?title=AppSuite:Open-Xchange_Updater ''Open-Xchange_Updater'']). The provider is available as soon as the according package is installed and at least one product can be installed/updated via it by the user. A pre-configured scenario 'oxupdaterinstall' is already contained in <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code>.<br />
<br />
== Configuring Onboarding scenarios ==<br />
<br />
Onboarding scenarios are configured through the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Each scenario starts with its own &quot;section&quot; in that YAML file by typing its unique identifier. All further attributes as outlined in chapter &quot;Onboarding scenarios&quot; are nested below that identifier.<br />
<br />
=== Easily enabling/disabling scenarios ===<br />
<br />
By default, Open-Xchange ships with a set of pre-defined scenarios that might apply to the most common installations. Each scenario can easily be enabled/disabled through its &quot;enabled&quot; Boolean attribute in the <code>/opt/open-xchange/etc/client-onboarding-scenarios.yml</code> YAML file. Executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool applies the changes without the need for restart.<br />
<br />
=== Translatable strings ===<br />
<br />
Those attributes ending with &quot;_t10e&quot; refer to localizable strings and are placed into &quot;client-onboarding-scenarios.pot&quot; file. Once such attributes ending with &quot;_t10e&quot; are changed/customized and/or added, the appropriate &quot;client-onboarding-scenarios.pot&quot; file needs to be re-created in order to get translated. For generating that &quot;client-onboarding-scenarios.pot&quot; file, please execute the /opt/open-xchange/sbin/parsei18nyaml command-line tool. That .pot file needs then be turned to the .po files for the individual languages.<br />
<br />
Thus changing any of the attributes ending with &quot;_t10e&quot; requires (provided that appropriate .po files are available in <code>/opt/open-xchange/i18n</code> directory) either a restart or executing <code>/opt/open-xchange/sbin/reloadconfiguration</code> command-line tool together with stop/start of the &quot;com.openexchange.i18n&quot; bundle.<br />
<br />
=== Scenario scope ===<br />
<br />
While the previously mentioned &quot;enabled&quot; attribute offers some kind of generic on/off switch, the properties outlined in this section allow defining the scope for a scenario. Scope in terms of<br />
<br />
* For what devices (from the set of those specified by providers) is that scenario available and<br />
* For which users is it available<br />
<br />
As explained above, each scenario specifies one or more type-compatible providers associated with it. In turn, each provider determines to which devices the scenario applies. In order to further control, which device and which users are allowed to access a certain scenario, there are appropriate options available in file <code>/opt/open-xchange/etc/client-onboarding.properties</code>. Every option is fully [http://oxpedia.org/wiki/index.php?title=ConfigCascade ''config-cascade''] aware and therefore can be controlled on a global, per context set, per context and per user basis.<br />
<br />
Thus, to make a scenario available for certain devices (as dictated by scenario’s providers) and for users as well, the scenario identifier needs to be added to the appropriate properties ending with &quot;.scenarios&quot; (for devices) and added to the &quot;com.openexchange.client.onboarding.enabledScenarios&quot; property (for user) as well:<br />
<br />
<blockquote>com.openexchange.client.onboarding.apple.mac.scenarios<br /><br />
com.openexchange.client.onboarding.apple.ipad.scenarios<br /><br />
com.openexchange.client.onboarding.apple.iphone.scenarios<br /><br />
com.openexchange.client.onboarding.android.tablet.scenarios<br /><br />
com.openexchange.client.onboarding.android.phone.scenarios<br /><br />
com.openexchange.client.onboarding.windows.desktop.scenarios<br />
<br />
com.openexchange.client.onboarding.enabledScenarios<br />
</blockquote><br />
Once a scenario is made accessible through configuration it is visible to users trying to perform a client onboarding using one of associated devices. However, whether a user is effectively allowed to execute that scenario is determined by the required capabilities of the denoted providers; if not allowed it gets displayed as an upsell opportunity.<br />
<br />
=== Configuring actions ===<br />
<br />
The type for a scenario determines what actions are associated with it to &quot;''transport''&quot; the onboarding information to the client. The types &quot;manual&quot; and &quot;link&quot; only show static information like displaying a link. In contrast the type &quot;plist&quot; allows several actions to transport the configuration profile onto the client. Thereof<br />
<br />
* E-Mail<br />
* SMS<br />
<br />
In order to utilize the &quot;E-Mail&quot; action, a special transport must be configured for system-composed E-Mails [http://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode#Share_Notifications ''as it is for using the sharing functionality'']. This transport is configured in noreply.properties. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.<br />
<br />
Using the SMS action requires a SIP Gate being available. Please check [http://oxpedia.org/wiki/index.php?title=AppSuite:SMS_Sipgate ''this documentation''] how to setup a SIP Gate for sending SMS to capable clients.<br />
<br />
Moreover, scenarios of type &quot;plist&quot; require having PLIST-signing enabled. Otherwise the device will show a warning when importing a received PLIST configuration profile. Please follow the instructions as outlined in [http://oxpedia.org/wiki/index.php?title=AppSuite:PList_signing ''this article''] how to enable and configure signing for PLIST files.<br />
<br />
== Adding custom scenarios ==<br />
<br />
The first thing to do, is to add an appropriate scenario configuration to the 'client-onboarding-scenarios.yml' file; e.g.<br />
<br />
<blockquote>mygoogleapp:<br /><br />
enabled: true<br /><br />
type: link<br /><br />
link:<br /><br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br /><br />
type: playstore<br /><br />
providers: [app]<br /><br />
alternatives: []<br /><br />
icon: fa-cloud<br /><br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br /><br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;<br />
</blockquote><br />
The next step is to make that scenario accessible through adapting 'client-onboarding.properties' file. Hence, the scenario identifier needs to be added to the devices, to which it applies (Android devices in this case):<br />
<br />
<blockquote>com.openexchange.client.onboarding.android.tablet.scenarios=..., mygoogleapp<br /><br />
com.openexchange.client.onboarding.android.phone.scenarios=..., mygoogleapp<br />
</blockquote><br />
Furthermore, that scenario needs to be made accessible to users as well:<br />
<br />
<blockquote>com.openexchange.client.onboarding.enabledScenarios=..., mygoogleapp<br />
</blockquote><br />
At last, a .pot file is supposed to be generated from the translatable strings using /opt/open-xchange/sbin/parsei18nyaml command-line tool to yield the .po files for the individual languages.<br />
<br />
Provided that target users do hold appropriate capabilities, they are allowed to execute that scenario. In the example above the &quot;app&quot; provider is specified, which does no require any capabilities. Hence, that scenario is available.<br />
<br />
== HowTos ==<br />
<br />
=== How can I quickly setup a default/test configuration ? ===<br />
<br />
# Install open-xchange-client-onboarding package<br />
# Edit <code>/opt/open-xchange/etc/client-onboarding.properties</code> and set <code>com.openexchange.client.onboarding.enabled</code> to <code>true</code> <br />
# Edit <code>noreply.properties</code> to enable autoconfig sending via email. PS: Have a fully working smtp login available like “noreply@yourdomain.tld”<br />
# Edit client-onboarding-scenarios.yml and set “enable” for : “driveappinstall” , “davsync” “davmanual” “mailsync” “mailmanual” to <code>true</code> <br />
# Now set the correct caldav/carddav server FQDNs in the corresponding files for your setup<br />
#*<code>client-onboarding-caldav.properties</code> <br />
#*<code>client-onboarding-carddav.properties</code><br />
# Restart OX process<br />
# Login to AppSuite. Click on Settings - Connect your device<br />
# Verify that you have following onboarding options available: <br />
#* windows -> imap/smtp details<br />
#* android/fon+tablet -> imap/smtp details<br />
#* android/fon+tablet -> drive app <br />
#* apple -> iphone -> imap/smtp config button<br />
#* apple -> iphone -> imap/smtp details for experts<br />
#* apple -> iphone -> calendar/addressbok -> config button<br />
#* apple -> iphone -> calendar/addressbok -> details for dav setup<br />
#* apple -> iphone -> drive app<br />
#* apple -> ipad -> imap/smtp config send email<br />
#* apple -> ipad -> imap/smtp config button<br />
#* apple -> ipad -> imap/smtp details for experts<br />
#* apple -> ipad -> calendar/addressbook config send email<br />
#* apple -> ipad -> calendar/addressbook config button<br />
#* apple -> ipad -> calendar/addressbook details for experts<br />
#* apple -> ipad -> drive app<br />
<br />
=== How can I quickly disable a certain scenario ===<br />
<br />
Simply enter the 'client-onboarding-scenarios.yml' file and go to the section specifying the target scenario. Switch the 'enabled' flag to &quot;false&quot; and execute /opt/open-xchange/sbin/reloadconfiguration command-line tool.<br />
<br />
E.g. to disable the OX Drive App:<br />
<br />
[[File:onboarding_3.png]]<br />
<br />
=== How can I disable the outdated ui parts like 'Downloads'? ===<br />
<br />
The wizard replaces and extends the functionality of the old Download Section in settings and the corresponding widgets. We recommend to disable these outdated parts:<br />
# widget: get ox drive<br />
# widget: update<br />
# settings entry: downloads<br />
<br />
'''Remove settings section 'Downloads' '''<br />
<br />
Edit ''/opt/open-xchange/etc/settings/appsuite.properties'' and add or change the value to true:<br />
* ''io.ox/core//settings/downloadsDisabled''<br />
<br />
'''Remove widgets'''<br />
<br />
To remove the both related portal widget/tiles please refer to the<br />
[[AppSuite:Configuring_portal_plugins#Disabling_a_tile_completely | portal plugins wiki page ]]<br />
<br />
* ''io.ox/portal/widget/oxdriveclients''<br />
* ''io.ox/portal/widget/updater''<br />
<br />
=== How can I add my own App? ===<br />
<br />
Provided that the App is accessible by a link (pointing to a commercial App Store or to a downloadable executable/installer), the generic &quot;app&quot; is the suitable provider to choose.<br />
<br />
Hence, an appropriate section is supposed to be added to the 'client-onboarding-scenarios.yml' file having a unique name and &quot;provider&quot; attribute set to &quot;[app]&quot;:<br />
<br />
<blockquote>mygoogleapp:<br /><br />
enabled: true<br /><br />
type: link<br /><br />
link:<br /><br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br /><br />
type: playstore<br /><br />
providers: [app]<br /><br />
alternatives: []<br /><br />
icon: fa-cloud<br /><br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br /><br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;<br />
</blockquote><br />
The attribute &quot;type&quot; needs to be set to &quot;link&quot;.<br />
<br />
The attribute &quot;link&quot; should be configured with:<br />
<br />
* &quot;url&quot; sub-attribute containing the actual link pointing to the URL location<br />
* &quot;type&quot; sub-attribute specifying of what type that link is: either &quot;appstore&quot;, &quot;macappstore&quot;, &quot;playstore&quot; or &quot;common&quot;.<br /><br />
The type &quot;common&quot; is supposed to be used for links that do not point to a commercial App Store, but to a downloadable executable/installer file.<br />
<br />
The &quot;icon&quot; attribute is supposed to contain a comma-separated list of Font Awesome icons (only the ones from v4.4.0 are currently supported) that represent the App; e.g.<br />
<br />
* &quot;fa-cloud&quot; for Drive/file-related nature<br />
* &quot;fa-calendar, fa-users&quot; for Calendar and Address Book synchronization<br />
* &quot;fa-envelope-o&quot; for Mail nature<br />
<br />
Next, the translatable display name and description should be set through setting the attributes &quot;displayName_t10e&quot; and &quot;description_t10e&quot;. As described previously, executing the /opt/open-xchange/sbin/parsei18nyaml command-line tool yields an appropriate .pot file, which can then be used for generating the individual .po file for the different translations.<br />
<br />
Finally, the 'client-onboarding.properties' file needs to be modified to specify the &quot;scope&quot; for that new scenario. Add the scenario’s unique name to the appropriate device properties and add it to &quot;com.openexchange.client.onboarding.enabledScenarios&quot; property as well.<br />
<br />
After executing /opt/open-xchange/sbin/reloadconfiguration command-line tool the new client onboarding scenario is available for the selected users/devices.<br />
<br />
=== How can I upsell my own app? ===<br />
<br />
Having the same prerequisites/steps as for &quot;How can I add my own App?&quot; the scenario description in the 'client-onboarding-scenarios.yml' file simply needs to be extended by the desired capabilities, which are supposed to be used for managing the upsell.<br />
<br />
Example<br />
<br />
<blockquote>mygoogleapp:<br /><br />
enabled: true<br /><br />
type: link<br /><br />
link:<br /><br />
url: http://play.google.com/store/apps?id=mygoogleapp.invalid<br /><br />
type: playstore<br /><br />
'''capabilities: &quot;mygoogleapp_capability&quot;'''<br /><br />
providers: [app]<br /><br />
alternatives: []<br /><br />
icon: fa-cloud<br /><br />
displayName_t10e: &quot;My App for synchronizing files&quot;<br /><br />
description_t10e: &quot;Synchronize your files with our Drive application.&quot;<br />
</blockquote><br />
The special &quot;capabilities&quot; attribute is only supported for scenarios of type &quot;link&quot; with the special &quot;app&quot; provider.<br />
<br />
With such a &quot;capabilities&quot; attribute only users, which have the &quot;mygoogleapp_capability&quot; capability are allowed to get the link. For those who don’t, the upsell opportunity will be displayed; e.g.<br />
<br />
<blockquote>[[File:onboarding_4.png]]<br />
</blockquote></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode&diff=21848AppSuite:Sharing and Guest Mode2016-04-21T14:06:18Z<p>Steffen.templin: /* Required Permissions and Capabilities */</p>
<hr />
<div><div class="title">Sharing and Guest Mode</div><br />
<br />
{{VersionFrom|7.8.0}}<br />
<br />
__TOC__<br />
<br />
== Introduction ==<br />
<br />
Starting with v7.8.0, the Open-Xchange server comes with a whole new concept to share contents with external people, allowing guest users to interact with the shared data in the same way as regular groupware users do. This article describes the underlying technical implications and outlines the different use cases.<br />
<br />
The main idea behind the new sharing concept is that guest users, i.e. external users without a regular account on the server, should be able to access the shared contents using the existing interfaces, especially the App Suite web interface. On the one hand, this includes consuming the shared data using the App Suite's advanced media viewing capabilities. On the other hand, this enables guests to edit existing as well as to create or upload new content in the groupware. Even real-time collaboration between internal users and guests in OX Documents is possible.<br />
<br />
The following chapters cover different topics regarding sharing and guest users and try to describe some technical background and impact where hosters, administrators or integrators might be interested in.<br />
<br />
== Creating Shares ==<br />
<br />
Basically, creating a share means adding an additional permission entity to the shared folder or item. Previously, this was only possible for &quot;internal&quot; entities, i.e. regular users or user groups. Now, the underlying permission system has been extended to support external entities, which can be either invited guest users, or special &quot;anonymous&quot; guest users who access a shared folder or item via a secret link. Anonymous and invited guest users are explained in more detail below.<br />
<br />
Sharing is available for the groupware modules Calendar, Contacts, Tasks and Drive (a.k.a. Infostore/Files). While the latter one also allows "writable" access for invited guest users, folders from the Calendar, Contacts and Tasks module may only be published in "read-only" mode to external guests.<br />
<br />
=== Invite Guests ===<br />
<br />
To share something to a guest user, it's possible to just add the e-mail address of the invitee as new permission entity for files and folders. The middleware then takes care to provision a new or reuse an existing account for the guest user, and equips him with the required permissions for accessing the contents. So, from a client's point of view, sharing something to a guest user is mostly the same process as sharing something to an internal user or group.<br />
<br />
=== Share Links ===<br />
<br />
Besides explicitly inviting a guest user to a share, it's also possible to just get a secret link for a folder or item. This will result in an additional &quot;anonymous&quot; guest entity in the permissions of the shared object, and will grant any user with the corresponding share link access the shared contents. To simplify the creation of share links, the clients will offer an additional &quot;wizard&quot; to quickly get a share link for a folder or item. Unlike invited guests which behave much like internal users, anonymous guest entities are strictly bound to the underlying folder or item, i.e. there is at most one anonymous permission entity per file or folder, as well as an anonymous permission entity can only be used for only once.<br />
<br />
=== Required Permissions and Capabilities ===<br />
<br />
Whether a user is allowed to create share links, invite external guests, or internal groups or users, depends on the following module access permissions and capabilities. Please note that share links no longer require <code>read_create_shared_folders</code> since Open-Xchange v7.8.1; this restriction was removed in order to allow simple publications also for non-groupware accounts, e.g. as defined by the <code>pim</code> or <code>pim_infostore</code> module access combinations.<br />
<br />
==== v7.8.0 ====<br />
* Create, update & remove share links: <code>read_create_shared_folders</code>, <code>share_links</code><br />
* Add, update or remove internal users and group permissions: <code>read_create_shared_folders</code><br />
* Add, update or remove external guest permissions: <code>read_create_shared_folders</code>, <code>invite_guests</code><br />
<br />
==== v7.8.1 ====<br />
* Create, update & remove share links: <code>share_links</code><br />
* Add, update or remove internal users and group permissions in modules Calendar, Contacts, Tasks: <code>read_create_shared_folders</code> for personal / <code>edit_public_folders</code> for public folders<br />
* Add, update or remove internal users and group permissions in module Drive: none<br />
* Add, update or remove external guest permissions in modules Calendar, Contacts, Tasks: <code>invite_guests</code>, and <code>read_create_shared_folders</code>, <code>read_create_shared_folders</code> for personal / <code>edit_public_folders</code> for public folders<br />
* Add, update or remove external guest permissions in module Drive: <code>invite_guests</code><br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Existing shares for a guest user or context may be listed using the commandline utility <code>listshares</code><br />
* The ability to create share links may be controlled via <code>com.openexchange.capability.share_links</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The ability to invite guest users may be controlled via <code>com.openexchange.capability.invite_guests</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The number of allowed share links per user may be specified via <code>com.openexchange.quota.share_links</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The number of allowed guest invitations per user may be specified via <code>com.openexchange.quota.invite_guests</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* Both quotas can also be set on a per-context basis via a 'changecontext' call and the <code>quota-module</code> and <code>quota-value</code> options, see [http://oxpedia.org/wiki/index.php?title=AppSuite:Context_management#changecontext]. The module IDs are accordingly <code>share_links</code> and <code>invite_guests</code>.<br />
* Quotas are always checked per-user, per default both are set to 100. You'll probably want to increase the quota for links when enabling the link mail feature available with OX App Suite 7.8.2.<br />
<br />
== Removing Shares ==<br />
<br />
The lifetime of shares is implicitly bound to the lifetime of the associated permission of the guest user entity. So, once a permission entity pointing to a (named or anonymous) guest user account is removed from the parent folder or item, this also leads to the removal of the associated share itself. Afterwards, the contents are no longer accessible for the guest user. For shares that were created with a specific expiry date, it is ensured that they can no longer be accessed via their share link after expiring. Additionally, expired shares are cleaned up periodically within a background task.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Shares may be revoked manually using the commandline utility <code>removeshares</code><br />
* The interval of the periodic cleanup task can be controlled via <code>com.openexchange.share.cleanup.periodicCleanerInterval</code> in <code>share.properties</code><br />
<br />
== Share Links &amp; Tokens ==<br />
<br />
Shares are accessed with a hyperlink that contains the so-called share &quot;token&quot;. This 24-byte token uniquely identifies the associated guest account on the system, and carries enough randomness that it can't be guessed. Explicitly invited guest users receive this hyperlink in the invitation mail to a share, while in case of an &quot;anonymous&quot; share where just the link itself was generated, it's up to the sharing user to distribute the link on his own. Besides the token, a share link may contain an additional path that points to the concrete folder and item, which just aids to jump to the shared item in the web interface directly. The following shows an example of a share link:<br />
<br />
<code>https://share.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/1/2/ODAxMDY</code><br />
<br />
If a guest user has been invited to more than one share in a context (based on his e-mail address), his individual share token remains equal, so that he will have access to all shared contents in the web interface after following any of the share links he received. However, the additional &quot;path&quot; still points to the concrete item. When inviting more than one guest user to the same share, each recipient will get his own individual share link.<br />
<br />
Once the share URL is requested from the server, the associated guest account is looked up and, depending of the guest type, the request is redirected to a specific login screen or directly into the App Suite web interface. More details regarding the different login modes are described at [[#Guest_Login_&_Session_Handling|Guest Login &amp; Session Handling]].<br />
<br />
After a share has been revoked (either explicitly, by removing the permission, or if the share is expired), share links can't be accessed any longer, and, after the last share for the guest user was removed, the guest account is removed from the system automatically.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The share token is stored as user attribute <code>com.openexchange.shareBaseToken</code> in the corresponding guest user account<br />
* The target database schema for a share and the associated guest account is extracted from the context identifier encoded in the share token<br />
<br />
== Guest Users ==<br />
<br />
As outlined above, guest users are created on demand once something is being shared. We basically distinguish between two types of guest users: Those that were invited explicitly by the sharing user, or &quot;anonymous&quot; guest users that are able to access by visiting the share link. Access for the latter one may optionally be secured with a fixed PIN code.<br />
<br />
For both kinds of guest users, a corresponding user account is provisioned dynamically on the system once a new share is created. Such a guest account is handled much similar as an account for a regular user, with the following main exceptions:<br />
<br />
* No access to the &quot;Mail&quot; module<br />
* No personal folders<br />
* No access to the &quot;Portal&quot;<br />
* No access to the global address book<br />
* Module access is restricted to only include modules from the actual shares<br />
<br />
All those restrictions are configured and enforced using the built-in mechanisms of the Open-Xchange Server, i.e. by a reduced set of capabilities (i.e. module permissions), or by selectively set permission bits in the folder tree for the virtual guest group. This ensures that guest users are only able to access things they explicitly have been invited to, as well as a transparent handling of guest accounts within all subsystems.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Guest users are stored much similar as regular users in the database (tables <code>user</code>, <code>prg_contacts</code>, <code>user_attribute</code>, <code>user_configuration</code>)<br />
* Additionally, the identifier of the user who (initially) created the guest account is stored in <code>user.guestCreatedBy</code>, i.e. if this column is not <code>0</code>, this entry refers to a guest user<br />
* All service calls and APIs that list or search users have been adjusted to be &quot;guest-aware&quot;, i.e. by default, guests users are not included in the output, yet may be included explicitly with additional parameters (namely <code>includeGuests</code> and <code>excludeUsers</code>)<br />
* Service calls and APIs that request data explicitly based on an entity's identifier are also working with guest users, i.e. if a specific idnetifier points to a guest, then the referenced guest data is returned<br />
<br />
=== Capabilities ===<br />
<br />
Guest users always have the <code>guest</code> capability set. Besides they are generally configured with a limited permission set, that allows them just to work with their shared items. This permission set includes:<br />
<br />
{|<br />
!Permission<br />
!Capability<br />
!Details<br />
|-<br />
|<code>deniedportal</code><br />
|<br />
|No <code>portal</code> capability<br />
|-<br />
|<code>editpublicfolders</code><br />
|<code>edit_public_folders</code><br />
|<br />
|-<br />
|<code>readcreatesharedfolders</code><br />
|<code>read_create_shared_folders</code><br />
|<br />
|-<br />
|<code>editpassword</code><br />
|<code>edit_password</code><br />
|Only for invited guests, not links<br />
|}<br />
<br />
Additionally, for every module the guest is having shared items in, the according module permission is granted, e.g. a shared drive folder results in permission <code>infostore</code> and the according capability. Guest users are never allowed to share folders or items on their own, i.e. the capabilities <code>share_links</code> and <code>invite_guests</code> can never be set.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
This limited capability set can be extended by configuration. Currently three modes are supported:<br />
<br />
{|<br />
!Mode<br />
!Description<br />
|-<br />
|deny_all<br />
|No further capabilities are applied to guest users, except ones that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code>.<br />
|-<br />
|static<br />
|A static list of capabilities is applied to guest users via the <code>com.openexchange.share.staticGuestCapabilities</code> property. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.<br />
|-<br />
|inherit<br />
|All capabilities of the user who &quot;created&quot; the guest, i.e. created the link or initially invited somebody, are applied to the guest user. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.<br />
|}<br />
<br />
The mode can be configured via the <code>com.openexchange.share.guestCapabilityMode</code> property in <code>share.properties</code>. This property is config-cascade capable, so it can for example be overridden for certain sets of contexts. The same applies to the <code>com.openexchange.share.staticGuestCapabilities</code> property.<br />
<br />
Due to this configuration mechanism it is possible to increase the user experience for guests and even allow some real collaboration. As an example one could apply the following configuration to allow guests to see preview images of files and edit shared documents with OX Text and OX Spreadsheet:<br />
<br />
<pre>com.openexchange.share.guestCapabilityMode = static<br />
com.openexchange.share.staticGuestCapabilities = document_preview, text, spreadsheet</pre><br />
<br />
=== Anonymous Guest Users ===<br />
<br />
If a &quot;share link&quot; is created, this results in an implicit creation of an anonymous guest user account on the server. The &quot;secret&quot; to access the shared contents is the share token itself that is encoded in the generated share link, so that everybody that knows the share link is able to access the shared contents. Optionally, such an anonymous share link may be secured with an additional PIN code. Guest users will be prompted to enter this PIN code when attempting to access the share.<br />
<br />
To have a strict separation between different shared contents, each time a folder or item is shared using the &quot;Get a link&quot; method, a designated anonymous guest account for this share is used. Consequently, each time such an anonymous share is revoked, this guest account is terminated again with no further delay. Additionally, such an anonymous guest entity can only be applied to the permission set of the folder or item the original link was created for, i.e. it's not possible to add more shared contents to an anonymous guest - in contrast to an invited, named guest user.<br />
<br />
Besides the common restrictions for guest accounts outlined above, the following applies for anonymous guest user accounts:<br />
<br />
* No e-mail address or display name<br />
* No password, if no PIN was assigned by the sharing user<br />
* A password that may only be changed by editing the link, if a PIN code was set<br />
* Anonymous guest users may only receive &quot;read-only&quot; access permissions to the shared item<br />
* Optionally, an expiry date can be applied for an anonymous guest user after which the share link is no longer accessible<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The PIN code for anonymous guest users is stored using symmetrical encryption in the database, therefore, an encryption key needs to be specified via the property <code>com.openexchange.share.cryptKey</code> in <code>share.properties</code><br />
<br />
=== Named Guest Users ===<br />
<br />
Internal users are able to invite a guest user to a folder or item explicitly by specifying the e-mail address of the recipient. Such &quot;named&quot; guest users are internally stored as individual guest users, identified by their e-mail address.<br />
<br />
If data is shared for the first time to the recipient in the context, a new guest user account is provisioned and an initial set of user permissions and capabilities is assigned. In case there are already shares in different contexts to the same recipient (based on his e-mail address), some existing user data like a display name or an assigned password is copied over if a cross-context database is available on the system.<br />
<br />
If the recipient has already been invited from the same or another internal user in the context to another share before, the new share is added to the guest user in a way that the underlying folder- and object permissions are taken over, and the user capabilities getting expanded as needed to cover all modules the shares are located in. Similarly, if a share to a named guest user is revoked and the underlying folder- and object-permissions are removed, the guest user capabilities are updated implicitly to reflect the modules of the remaining shares.<br />
<br />
After the last share to a named guest user has been revoked, the user has no longer access to any data. The account itself gets removed from the context automatically after a configurable expiry time. Additionally, any data that is stored for the guest user in the cross-context database is removed once the guest user has been deleted from all contexts in the system.<br />
<br />
In contrast to an &quot;anonymous&quot; guest user, a named guest user has access to all shared items from a context after logging in, since the permissions get added to an existing guest user account automatically. For entering the web interface, he may use any of the share links that were sent to him in the different notification messages. Those links usually point to an individual share target like a folder or file, but the guest user may navigate to the other shared contents using the folder tree of the web interface in the same way as regular groupware users do. Similarly, if the guest user has access to shares from different modules, the modules can be switched in the web interface as usual.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The timespan after which an unused named guest user should be removed from the system can be configured via <code>com.openexchange.share.cleanup.guestExpiry</code> in <code>share.properties</code> - this value may also be set to <code>0</code> to force an immediate removal<br />
* For the removal of no longer needed guest user accounts, a periodical cleanup task is scheduled based on the interval of <code>com.openexchange.share.cleanup.periodicCleanerInterval</code><br />
* Whether a cross-context database is considered for guest users may be configured via <code>com.openexchange.share.crossContextGuests</code><br />
<br />
== Guest Login &amp; Session Handling ==<br />
<br />
Based on the underlying guest user account, different login operations with different authentication workflows are possible.<br />
<br />
=== Authentication ===<br />
<br />
We have basically three different authentication options for guest users accessing a share, each of them having their own characteristics.<br />
<br />
==== Anonymous ====<br />
<br />
* Access is granted without providing additional authentication information, the knowledge of the link is sufficient<br />
* When accessing the share link, a guest session is spawned implicitly<br />
* Initially supplied cookies are considered to recycle an existing session<br />
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)<br />
<br />
==== Anonymous with PIN ====<br />
<br />
* Access is granted for anonymous guest users providing a password / PIN code<br />
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=anonymous</code><br />
* User can then enter his PIN code, client executes the <code>anonymous_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)<br />
* Password can't be changed by an anonymous user<br />
* Password can be re-constructed / changed by sharing user<br />
<br />
==== Guest without Password ====<br />
<br />
* Access is granted without providing additional authentication information, the knowledge of the guest's individual link is sufficient<br />
* When accessing the share link, a guest session is spawned implicitly<br />
* Exiting cookies are considered to recycle an existing session<br />
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)<br />
* Guest user may choose an individual password at a later stage<br />
<br />
==== Guest with Password ====<br />
<br />
* Access is granted for guest users providing a user name and password.<br />
* Much similar to a regular groupware user<br />
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=guest</code> and <code>login_name=&lt;NAME&gt;</code><br />
* The login name is used to pre-fill the username input<br />
* User can then enter his password, client executes the <code>guest_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)<br />
* Password can be changed by guest user<br />
* Guest user may reset his password if he can't remember<br />
<br />
=== Guest Hostname ===<br />
<br />
For serving shares, a separate guest hostname needs to be configured. This is mainly required to prevent guest- and regular user sessions using the same cookie container when logged in in the same client (otherwise, the cookie holding the alternative session identifier as well as other cookies would get overwritten concurrently). Additionally, this allows to have separate entry points to the web client for guest- and regular users. <br />
<br />
The hostname for guests is used when generating external share links, as well as at other locations where hyperlinks are constructed in the context of guest users. Usually, the guest hostname refers to a separate subdomain of the installation like <code>share.example.com</code>, and is defined as an additional named virtual host pointing to the web client's document root in the webserver's configuration. <br />
<br />
Once the webserver configuration is done and the web client is accessible using the guest hostname, this hostname needs to be specified in the backend configuration, too. In simple scenarios, where a fixed guest hostname should be used for the installation, this can be done statically in a configuration file. This setting may also be overridden per context via the Config Cascade. In case a dedicated hostname service is installed (for example <code>open-xchange-hostname-ldap</code>), this hostname service is also supposed to supply the guest hostname. <br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The guest hostname may be specified via <code>com.openexchange.share.guestHostname</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The guest hostname may also be supplied via dedicated hostname services like <code>open-xchange-hostname-config-cascade</code> or <code>open-xchange-hostname-ldap</code><br />
* For test purposes, guests may also access the web interface using the same host as regular users do, however, this might lead to unexpected results (missing images, sessions timing out, auto-login malfunction...)<br />
<br />
=== Cookies ===<br />
<br />
Guest sessions basically make use of the same cookies as regular user sessions do. This includes the JSESSONID cookie for the JVM route, as well as the <code>open-xchange-secret-&lt;hash&gt;</code> and <code>open-xchange-public-session-&lt;hash&gt;</code> cookies. Additionally, if configured, the client may also issue a <code>store</code> request to persist the open-xchange-session-<hash> cookie. This cookie may then be used to auto-login the guest client into the previously used session if it is still valid.<br />
<br />
Besides the common cookies, another special cookie is set: <code>open-xchange-share-&lt;hash&gt;</code>. The value contains the unique share token bound to the guest user accessing the share. here, the cookie hash is calculated as it's done for ordinary sessions, so that there can only be one <code>open-xchange-share-&lt;hash&gt;</code> cookie in a client at the same time. Whenever an auto-login request is issued by the client, the server checks for the existence of this &quot;share&quot; cookie, and, once recognized and checked for validity, it will try to perform the auto-login for an existing guest session first, i.e. using the session cookie based on the special guest hash calculation outlined above. Otherwise, the common auto-login process takes place. The &quot;share&quot; cookie is removed once the guest session terminates, i.e. the guest user logs out.<br />
<br />
Since guest users access the web interface on a separate (sub)domain (see [[#Guest_Hostname|Guest Hostname]] above for details), guest session cookies won't interfere with cookies of a regular session on the same client. This allows to use the regular user session as well as one or more guest sessions in parallel - e.g. if the sharing user quickly wants to check how the contents appear for the guest user after generating a share link.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Whether guest sessions are enabled for auto-login is configurable via the property <code>com.openexchange.share.autoLogin</code> in <code>share.properties</code><br />
* By default, the cookie TTL for guest sessions is inherited from the TTL for cookies of regular sessions as defined by <code>com.openexchange.cookie.ttl</code> - this default may be overridden by defining a timespan at <code>com.openexchange.share.cookieTTL</code><br />
<br />
=== Login Modes ===<br />
<br />
When accessing a share link, one of the following login modes is triggered to acquire a session and forward the client to the share target. The executed login operation and redirect depends on the authentication mode of underlying guest account, the share target iteself, and the client accessing the share.<br />
<br />
==== Redirect to Target ====<br />
<br />
In case a share is accessible without providing credentials, the client is redirected to the share target directly, i.e. without prompting for a username or password. By default, the client is redirected to the target in the App Suite web interface by responding the <code>GET</code> request to the share link with <code>HTTP 302</code>, and a location header like the following:<br />
<br />
<code>Location: /appsuite/ui#!&amp;session=80c711019d6f48b5bec9cd82758e3308&amp;store=true&amp;user=&amp;user_id=642&amp;context_id=1&amp;m=files&amp;f=41042</code><br />
<br />
The session for the guest user is created implicitly in the backend after checking the share link's validity, and the client is instructed to store appropriate cookies in the redirect response, including the &quot;share&quot; cookie:<br />
<br />
<code>Set-Cookie: open-xchange-secret-aNobP2G9wLHJ6sMr7vtTA=38ee770d6e4f42ab8366d91db3279931; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=cae6a3e712ac429e9da9194abd389cb3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ad50ac00418fbcdad50ac1418f94fb181d51b8fa7b2bde3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br />
<br />
==== Redirect to Login Screen ====<br />
<br />
If additional credentials, i.e. an additional PIN code or username/password combination, are required to access a share target, and no &quot;special client&quot; like an iCal consumer is detected by the backend, the client is redirected to the login screen of the app suite webinterface. The GET request to the share link is answered with statuscode HTTP 302, and a location header depending on the required credentials to access the share.<br />
<br />
If the share ought to be accessed anonymously, but protected by a PIN code, a location like the following is added to the response header:<br />
<br />
<code>Location: /appsuite/ui#!&amp;share=08b4b6110151f1bd7d4b610151f0405d9fc8bb89a887f04e&amp;login_type=anonymous&amp;message_type=INFO&amp;message=Tony%20Parker%20has%20shared%20the%20folder%20%22Pictures%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&amp;target=151ebb38</code><br />
<br />
For shares to dedicated guest users identified by their e-mail address, the redirect location looks like follows:<br />
<br />
<code>Location: /appsuite/ui#!&amp;share=4ac9eb590f9ca4d2ac9eb58f9ca611ec9b4f4638d288c8c0&amp;login_type=guest&amp;message_type=INFO&amp;message=Tony%20Parker%20has%20shared%20the%20file%20%22Agenda.pdf%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&amp;login_name=ray%40example.com&amp;target=4444cbc7</code><br />
<br />
The redirect response already contains the <code>Set-Cookie</code> header for the JVM route. On the redirect target, the client should request the PIN code or password from the user, and then issue a special login request, supplying the share token and optional target from the URL parameters, and the password as URL encoded form data in the request body, similar to the usual login request via POST. After successful authentication, the login response includes, along with the common login response properties like the session identifier, information about the share target being accessed:<br />
<br />
<code>{&quot;session&quot;:&quot;b89af2c2ce494ce4b4573c0632b48e89&quot;,&quot;user&quot;:&quot;ray@example.com&quot;,&quot;user_id&quot;:660,&quot;context_id&quot;:1,&quot;locale&quot;:&quot;en_US&quot;,&quot;module&quot;:&quot;files&quot;,&quot;folder&quot;:&quot;10&quot;,&quot;item&quot;:&quot;10/456398&quot;, ... }</code><br />
<br />
Additionally, the client is instructed to store the secret cookies:<br />
<br />
<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ac9eb590f9ca4d5ac9eb58f9ca641ec9b4f4638d288c8a0; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-secret-MBIRg9bJBLduCcosqQBCw=70187de16f844be6880c18be373b953d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=4e797a59758a4dd7b763912472ccf26d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br />
<br />
Afterwards, the client is able to use the session to access the share target as usual.<br />
<br />
=== Session Lifecycle ===<br />
<br />
Generally, guest sessions on the server are treated just like the sessions of ordinary users. Especially, guest sessions are also held in the local session containers of the backend host they're associated with. However, by default guest sessions are marked as <code>transient</code>, i.e. they are not moved to the long-term session containers, nor they are put into the distributed session storage.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Guest sessions are also accounted in the monitoring outputs (e.g. in the sessions per container graphs)<br />
* The <code>transient</code> handling of guest sessions may be changed via the property <code>com.openexchange.share.transientSessions</code> in <code>share.properties</code><br />
<br />
=== Logout ===<br />
<br />
Guest sessions are terminated once a logout request is issued by the client, i.e. the user clicks the &quot;Logout&quot; button in the web interface, just like it is done for regular sessions. Additionally, guest sessions expire in the backend when not being used for a while, the actual timeout depends on the configured default session lifetime and whether they are treated as &quot;transient&quot; or not, as explained above.<br />
<br />
Since guest users are not able to use the default login page for regular users, a custom logout location for guest users should be specified where guest users are taken to after clicking logout explicitly, or if their session expired.<br />
<br />
If a share is consumed &quot;directly&quot;, e.g. by downloading the binary contents of a file share directly (see [[#Consuming_Shares|Consuming Shares]] for details), the guest sessions is terminated instantly after serving the request.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The logout location for guest accounts can be customized via <code>guestLogoutLocation</code> in the file <code>as-config.yml</code> (see file <code>as-config-default.yml</code> for an example)<br />
<br />
== Share Notifications ==<br />
<br />
With the new sharing concept, notification mails can be sent out to the permission entities (i.e. internal or guest users) of folders or items. Mechanisms exist to send out such mails implicitly or explicitly. Notifications are sent out implicitly, if externals are invited as guests and can also be sent out for internal invitations, if configured so. The client (e.g. App Suite UI) decides on its own whether implicit notifications shall be sent when updating a folders or items permissions. Besides there are separate API calls for sending out notification messages explicitly. Its on the client to provide this functionality to its users. This makes it possible to re-send a link to a folder or item to an existing permission entity.<br />
<br />
Sending out links to shared folders and items is not the only case for notification messages, it can also be necessary to send out system notifications to guest users. Currently this is the case when a guest user secured his account with a password and needs to reset that password, because he cannot remember.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* A special transport must be configured for system notifications and cases where the sharing user has no configured webmail account. This transport is configured in <code>noreply.properties</code>. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.<br />
* It is possible to disable the implicit notification of internal users about shared folders or items at all by setting <code>com.openexchange.share.notifyInternal</code> in <code>share.properties</code> to <code>false</code>.<br />
* The layout of notifications mails can be changed via <code>as-config.yml</code>. All available properties are defined and explained in <code>as-config-defaults.yml</code>.<br />
<br />
== API Access ==<br />
<br />
From a client's point of view, guest users basically don't differ from regular users, although they usually have limited capabilities, for example no mail access or no personal folders. However, all those differences are reflected within the regular permission- and capability-concepts, so that existing clients, once the guest user is authenticated and has a valid session, continue to work transparently, and use the same API calls as with a regular groupware user.<br />
<br />
To create or manage shares and guest users, the HTTP API has been extended at various locations. The following list gives an overview about the changes, derived from the corresponding software change requests.<br />
<br />
=== Format change for object identifiers of the default &quot;infostore&quot; account ===<br />
<br />
As preparation for individual object permissions where a file can be accessed from different folder &quot;views&quot;, the object IDs for documents in the default &quot;infostore&quot; file storage account will get enhanced with the prefixing folder ID.<br />
<br />
The identifiers will now be of format <code>&lt;some numbers&gt;/&lt;more numbers&gt;</code>. Object identifiers are already of type <code>String</code>, so this change should usually be transparent to clients. However, there may be some clever clients out there that for example tried to interpret the string of numerical characters as number, so client developers should double-check their implementation for compatibility. They most likely would run into trouble when coping with non-infostore file storages anyway.<br />
<br />
=== Object permissions for files ===<br />
<br />
In order to define permissions on object-level, a new property <code>object_permissions</code> for objects of type <code>infoitem</code> is introduced. Each time the underlying folder permissions are not sufficient to access an item, those object permissions are taken into account. Object permissions are stored as an array of Object Permission objects as defined below within the detailed infoitem data, the column ID is <code>108</code>.<br />
<br />
Details about the JSON structure are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionFlags HTTP API: Object Permission Flags]<br />
<br />
=== New field for &quot;user&quot; data: &quot;guest_created_by&quot; ===<br />
<br />
A new property has been introduced for users that needs to be exposed in our HTTP API, too. The following property is added to the detailed user data object:<br />
<br />
* ID: 616<br />
* Name: guest_created_by<br />
* Type: Number<br />
* Value: Contains the ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users<br />
<br />
The property is read-only and can't be removed or set by clients.<br />
<br />
See also:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedUserData HTTP API: Detailed User Data]<br />
<br />
=== Extend folder- and object permissions for addressing external guests ===<br />
<br />
For sharing files- or folders to external guests, the folder- and object permission objects are extended with additional properties. Those extended properties can be set during creation or update of the parent folder or file. The underlying shares and guest user entities for the referenced recipients are created automatically along with folder/file creation/update. Afterwards, the external recipients appear as regular &quot;user&quot; entities in the permission arrays in subsequent &quot;get&quot; requests.<br />
<br />
Details about the extended JSON structure are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#PermissionObject HTTP API: Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]<br />
<br />
=== New Ajax module: share/management ===<br />
<br />
To work with shares, a new Ajax module is introduced.<br />
<br />
The available actions in the module are described at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Module_.22share.2Fmanagement.22_.28preliminary.2C_available_with_v7.8.0.29 HTTP API: Module share management]<br />
<br />
=== New column &quot;shareable&quot; in detailed infoitem data ===<br />
<br />
Clients want to know quickly if an infostore item is shareable or not. A new (read-only) property named <code>shareable</code> of type Boolean with column identifier <code>109</code> is introduced for &quot;detailed infoitem data&quot;. If &quot;true&quot;, the can be considered as shareable, i.e. the item's object permissions may be adjusted by the user.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]<br />
<br />
=== New action &quot;shares&quot; in module folder ===<br />
<br />
To provide an overview of all folders of a certain modules that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>folders</code>. It returns all personal folders of a certain module that are shared to other entities.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared folders]<br />
<br />
=== New action &quot;shares&quot; in module infostore ===<br />
<br />
To provide an overview of all files that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>infostore</code>. It returns all personal files that are shared to other entities.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared infoitems]<br />
<br />
=== New fields to retrieve extended permissions of files and folders ===<br />
<br />
Clients would like to have more details about permission entities folders directly. A new read-only property named <code>com.openexchange.share.extendedPermissions</code> is introduced for &quot;Detailed folder data&quot;, with column identifier <code>3060</code>. It basically contains the same as the regular <code>permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.<br />
<br />
Similarly, a new read-only property named <code>com.openexchange.share.extendedObjectPermissions</code> is introduced for &quot;Detailed infoitem data&quot;, with column identifier <code>7010</code>. It basically contains the same as the regular <code>object_permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.<br />
<br />
Further information about the JSON structure is available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedPermissionObject HTTP API: Extended Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedObjectPermissionObject HTTP API: Extended Object Permission Object]<br />
<br />
== Consuming Shares ==<br />
<br />
Depending on the shared contents and the requesting user agent, shares may be consumed in a couple of different ways. The concrete response to a request to the share URL is evaluated by the share servlet in the backend.<br />
<br />
=== App Suite ===<br />
<br />
The default handling for all shares is forwarding them to the App Suite web interface, where the shared contents are made available through the existing client. Based on the underlying guest account, the client is either forwarded to the login prompt, or taken directly to the share target if no credentials need to be provided. This process is described in more detail at [[#Guest_Login_&_Session_Handling|Guest Login &amp; Session Handling]].<br />
<br />
=== Direct Download ===<br />
<br />
Shares to a single file may also be downloaded directly by clients, without opening them in the web interface first. This is indicated by an additional parameter appended to the plain share link, and can be specified in the following ways:<br />
<br />
* Append <code>dl</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?dl=true</code><br />
* Specify <code>delivery</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?delivery=download</code><br />
<br />
If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an &quot;anonymous&quot; share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like &quot;Guest&quot;.<br />
<br />
=== Get iCal ===<br />
<br />
Shares to a single calendar- or task-folder may also be downloaded directly by clients as iCal files, without opening them in the web interface first. This standard format allows to consume event data directly using various calendaring clients, which often can be configured to subscribe an external calendar source.<br />
<br />
Once a share link to a calendar- or task-folder is requested by the client, the <code>Accept</code>- and <code>User-Agent</code> headers of the request are evaluated. If the <code>Accept</code> header is either set to <code>text/calendar</code> or <code>text/iCal</code>, or if the <code>User-Agent</code> header denotes a well-known client like Microsoft Outlook or Mozilla Thunderbird w/ Lightning, the contents of the shared folder are converted to an iCal file that is directly written back in the response.<br />
<br />
To force the iCal output, an additional parameter may be appended to the plain share link:<br />
<br />
* Append <code>ical</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?ical=true</code><br />
<br />
If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an &quot;anonymous&quot; share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like &quot;Guest&quot;.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The interval of task- and appointment data considered for conversion to iCal can be adjusted via <code>com.openexchange.share.handler.iCal.futureInterval</code> and <code>com.openexchange.share.handler.iCal.pastInterval</code> in configuration file <code>share.properties</code><br />
<br />
== Cross-context functionality ==<br />
<br />
As already mentioned in previous sections the administrator is able to configure if guests should be handled per context (default) or server wide by using the configuration parameter <code>com.openexchange.share.crossContextGuests</code>.<br />
<br />
If set to <code>true</code> the guests email address is used to recognize if there is already a registered user with the given address and aligns the stored password to the already existing guest user. In addition to the password (which is the most important parameter this feature is about) even the users contact data gets synchronized.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* To handle user and contact data across contexts boundaries the feature has to be enabled before a guest receives the first share. Guests that receive shares before the activation cannot be considered within the alignment process. Only latter shares will be considered.<br />
* At the moment this feature does only sync user and contact related data (no shared content). If the user got two shares from different contexts he will only see shares related to the given link.<br />
<br />
== Publish/Subscribe vs. Sharing ==<br />
<br />
The upcoming sharing features are going to replace the previously used OXMF &quot;publications&quot;, allowing guest users to interact with the shared data in the same way as regular groupware users do. However, since the underlying concepts and their technical realization are completely different, a seamless migration between publications and shares is not possible without some drawbacks.<br />
<br />
The following list gives an overview of the main discrepancies:<br />
<br />
* Custom templates for OXMF publication targets<br />An adminsitrator/admin may have defined some custom publication targets that are using the published data in a special way. While shares would still make all the data available (mainly via the web interface), this would only be a drop-in replacement for the ordinary &quot;view the publication in a browser&quot; use case, but not for anything beyond that scope.<br />
* Subscribe of publications<br />Publications from one user can be added to another user's groupware using the &quot;subscribe&quot; functionality, making use of the embedded microformat data of publications (OXMF). For sharing, we will not have a similar feature in the first iteration, so migrating an existing publication to a share would also stop it from being subscribable.<br />
* Deep links to download files of publications<br />Files behind an infostore publication were accessible behind a static URL, which would theoretically allow them to be requested independently of the parent publication (e.g. images linked from an external website). While the entry URL to a publication would be mappable to a corresponding share URL, converting existing publications to shares would at least break such deep links.<br />
<br />
Because of the above points and the whole different concept, we do not migrate existing publications to shares. Instead, the default behavior will be:<br />
<br />
* No new OXMF publications or subscriptions can be created by default<br />
* The web client does no longer give the option to publish or subscribe in the OXMF format<br />
* Existing OXMF publications / subscriptions can't be updated<br />
* Existing OXMF publications continue to work as is, including associated subscriptions<br />
* Yet it's still possible to delete existing publications and subscriptions<br />
* Therefore, the menu section &quot;Publications and Subscriptions&quot; will still be available (if there's at least one publication or subscription)<br />
<br />
Exceptions to these rules cover special internal subscriptions to 3rd party services like addressbooks from LinkedIn or Xing, as well as the auto-publish feature of mail attachments exceeding a specific size.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The possibility to create/update OXMF publications via HTTP-API may be configured via <code>com.openexchange.publish.createModifyEnabled</code> in file <code>publications.properties</code><br />
* The possibility to create/update OXMF subscriptions via HTTP-API may be configured via <code>com.openexchange.subscribe.microformats.createModifyEnabled</code> in file <code>microformatSubscription.properties</code><br />
<br />
<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode&diff=21847AppSuite:Sharing and Guest Mode2016-04-21T14:05:56Z<p>Steffen.templin: /* Required Permissions and Capabilities */</p>
<hr />
<div><div class="title">Sharing and Guest Mode</div><br />
<br />
{{VersionFrom|7.8.0}}<br />
<br />
__TOC__<br />
<br />
== Introduction ==<br />
<br />
Starting with v7.8.0, the Open-Xchange server comes with a whole new concept to share contents with external people, allowing guest users to interact with the shared data in the same way as regular groupware users do. This article describes the underlying technical implications and outlines the different use cases.<br />
<br />
The main idea behind the new sharing concept is that guest users, i.e. external users without a regular account on the server, should be able to access the shared contents using the existing interfaces, especially the App Suite web interface. On the one hand, this includes consuming the shared data using the App Suite's advanced media viewing capabilities. On the other hand, this enables guests to edit existing as well as to create or upload new content in the groupware. Even real-time collaboration between internal users and guests in OX Documents is possible.<br />
<br />
The following chapters cover different topics regarding sharing and guest users and try to describe some technical background and impact where hosters, administrators or integrators might be interested in.<br />
<br />
== Creating Shares ==<br />
<br />
Basically, creating a share means adding an additional permission entity to the shared folder or item. Previously, this was only possible for &quot;internal&quot; entities, i.e. regular users or user groups. Now, the underlying permission system has been extended to support external entities, which can be either invited guest users, or special &quot;anonymous&quot; guest users who access a shared folder or item via a secret link. Anonymous and invited guest users are explained in more detail below.<br />
<br />
Sharing is available for the groupware modules Calendar, Contacts, Tasks and Drive (a.k.a. Infostore/Files). While the latter one also allows "writable" access for invited guest users, folders from the Calendar, Contacts and Tasks module may only be published in "read-only" mode to external guests.<br />
<br />
=== Invite Guests ===<br />
<br />
To share something to a guest user, it's possible to just add the e-mail address of the invitee as new permission entity for files and folders. The middleware then takes care to provision a new or reuse an existing account for the guest user, and equips him with the required permissions for accessing the contents. So, from a client's point of view, sharing something to a guest user is mostly the same process as sharing something to an internal user or group.<br />
<br />
=== Share Links ===<br />
<br />
Besides explicitly inviting a guest user to a share, it's also possible to just get a secret link for a folder or item. This will result in an additional &quot;anonymous&quot; guest entity in the permissions of the shared object, and will grant any user with the corresponding share link access the shared contents. To simplify the creation of share links, the clients will offer an additional &quot;wizard&quot; to quickly get a share link for a folder or item. Unlike invited guests which behave much like internal users, anonymous guest entities are strictly bound to the underlying folder or item, i.e. there is at most one anonymous permission entity per file or folder, as well as an anonymous permission entity can only be used for only once.<br />
<br />
=== Required Permissions and Capabilities ===<br />
<br />
Whether a user is allowed to create share links, invite external guests, or internal groups or users, depends on the following module access permissions and capabilities. Please note that share links no longer require <code>read_create_shared_folders</code> since Open-Xchange v7.8.1; this restriction was removed in order to allow simple publications also for non-groupware accounts, e.g. as defined by the <code>pim</code> or <code>pim_infostore</code> module access combinations.<br />
<br />
==== v7.8.0 ====<br />
* Create, update & remove share links: <code>read_create_shared_folders</code>, <code>share_links</code><br />
* Add, update or remove internal users and group permissions: <code>read_create_shared_folders</code><br />
* Add, update or remove external guest permissions: <code>read_create_shared_folders</code>, <code>invite_guests</code><br />
<br />
==== v7.8.1 ====<br />
* Create, update & remove share links: <code>share_links</code><br />
* Add, update or remove internal users and group permissions in modules Calendar, Contacts, Tasks: <code>read_create_shared_folders</code> for personal / <code>edit_public_folders</code> for public folders<br />
* Add, update or remove internal users and group permissions in module Drive: none<br />
* Add, update or remove external guest permissions in modules Calendar, Contacts, Tasks: <code>invite_guests</code>, and <code>read_create_shared_folders</code>, <code>read_create_shared_folders</code> for personal / <code>edit_public_folders</code> for public folders<br />
* Add, update or remove external guest permissions in module Drive: <code>invite_guests</code><br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Existing shares for a guest user or context may be listed using the commandline utility <code>listshares</code><br />
* The ability to create share links may be controlled via <code>com.openexchange.capability.share_links</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The ability to invite guest users may be controlled via <code>com.openexchange.capability.invite_guests</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The number of allowed share links per user may be specified via <code>com.openexchange.quota.share_links</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The number of allowed guest invitations per user may be specified via <code>com.openexchange.quota.invite_guests</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* Both quotas can also be set on a per-context basis via a 'changecontext' call and the <code>quota-module</code> and <code>quota-value</code> options, see [http://oxpedia.org/wiki/index.php?title=AppSuite:Context_management#changecontext]. The module IDs are accordingly <code>share_links</code> and <code>invite_guests</code>.<br />
* Quotas are always checked per-user, per default both are set to 100. You'll probably want to increase the quota for links when enabling the link mail feature available with OXY App Suite 7.8.2.<br />
<br />
== Removing Shares ==<br />
<br />
The lifetime of shares is implicitly bound to the lifetime of the associated permission of the guest user entity. So, once a permission entity pointing to a (named or anonymous) guest user account is removed from the parent folder or item, this also leads to the removal of the associated share itself. Afterwards, the contents are no longer accessible for the guest user. For shares that were created with a specific expiry date, it is ensured that they can no longer be accessed via their share link after expiring. Additionally, expired shares are cleaned up periodically within a background task.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Shares may be revoked manually using the commandline utility <code>removeshares</code><br />
* The interval of the periodic cleanup task can be controlled via <code>com.openexchange.share.cleanup.periodicCleanerInterval</code> in <code>share.properties</code><br />
<br />
== Share Links &amp; Tokens ==<br />
<br />
Shares are accessed with a hyperlink that contains the so-called share &quot;token&quot;. This 24-byte token uniquely identifies the associated guest account on the system, and carries enough randomness that it can't be guessed. Explicitly invited guest users receive this hyperlink in the invitation mail to a share, while in case of an &quot;anonymous&quot; share where just the link itself was generated, it's up to the sharing user to distribute the link on his own. Besides the token, a share link may contain an additional path that points to the concrete folder and item, which just aids to jump to the shared item in the web interface directly. The following shows an example of a share link:<br />
<br />
<code>https://share.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/1/2/ODAxMDY</code><br />
<br />
If a guest user has been invited to more than one share in a context (based on his e-mail address), his individual share token remains equal, so that he will have access to all shared contents in the web interface after following any of the share links he received. However, the additional &quot;path&quot; still points to the concrete item. When inviting more than one guest user to the same share, each recipient will get his own individual share link.<br />
<br />
Once the share URL is requested from the server, the associated guest account is looked up and, depending of the guest type, the request is redirected to a specific login screen or directly into the App Suite web interface. More details regarding the different login modes are described at [[#Guest_Login_&_Session_Handling|Guest Login &amp; Session Handling]].<br />
<br />
After a share has been revoked (either explicitly, by removing the permission, or if the share is expired), share links can't be accessed any longer, and, after the last share for the guest user was removed, the guest account is removed from the system automatically.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The share token is stored as user attribute <code>com.openexchange.shareBaseToken</code> in the corresponding guest user account<br />
* The target database schema for a share and the associated guest account is extracted from the context identifier encoded in the share token<br />
<br />
== Guest Users ==<br />
<br />
As outlined above, guest users are created on demand once something is being shared. We basically distinguish between two types of guest users: Those that were invited explicitly by the sharing user, or &quot;anonymous&quot; guest users that are able to access by visiting the share link. Access for the latter one may optionally be secured with a fixed PIN code.<br />
<br />
For both kinds of guest users, a corresponding user account is provisioned dynamically on the system once a new share is created. Such a guest account is handled much similar as an account for a regular user, with the following main exceptions:<br />
<br />
* No access to the &quot;Mail&quot; module<br />
* No personal folders<br />
* No access to the &quot;Portal&quot;<br />
* No access to the global address book<br />
* Module access is restricted to only include modules from the actual shares<br />
<br />
All those restrictions are configured and enforced using the built-in mechanisms of the Open-Xchange Server, i.e. by a reduced set of capabilities (i.e. module permissions), or by selectively set permission bits in the folder tree for the virtual guest group. This ensures that guest users are only able to access things they explicitly have been invited to, as well as a transparent handling of guest accounts within all subsystems.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Guest users are stored much similar as regular users in the database (tables <code>user</code>, <code>prg_contacts</code>, <code>user_attribute</code>, <code>user_configuration</code>)<br />
* Additionally, the identifier of the user who (initially) created the guest account is stored in <code>user.guestCreatedBy</code>, i.e. if this column is not <code>0</code>, this entry refers to a guest user<br />
* All service calls and APIs that list or search users have been adjusted to be &quot;guest-aware&quot;, i.e. by default, guests users are not included in the output, yet may be included explicitly with additional parameters (namely <code>includeGuests</code> and <code>excludeUsers</code>)<br />
* Service calls and APIs that request data explicitly based on an entity's identifier are also working with guest users, i.e. if a specific idnetifier points to a guest, then the referenced guest data is returned<br />
<br />
=== Capabilities ===<br />
<br />
Guest users always have the <code>guest</code> capability set. Besides they are generally configured with a limited permission set, that allows them just to work with their shared items. This permission set includes:<br />
<br />
{|<br />
!Permission<br />
!Capability<br />
!Details<br />
|-<br />
|<code>deniedportal</code><br />
|<br />
|No <code>portal</code> capability<br />
|-<br />
|<code>editpublicfolders</code><br />
|<code>edit_public_folders</code><br />
|<br />
|-<br />
|<code>readcreatesharedfolders</code><br />
|<code>read_create_shared_folders</code><br />
|<br />
|-<br />
|<code>editpassword</code><br />
|<code>edit_password</code><br />
|Only for invited guests, not links<br />
|}<br />
<br />
Additionally, for every module the guest is having shared items in, the according module permission is granted, e.g. a shared drive folder results in permission <code>infostore</code> and the according capability. Guest users are never allowed to share folders or items on their own, i.e. the capabilities <code>share_links</code> and <code>invite_guests</code> can never be set.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
This limited capability set can be extended by configuration. Currently three modes are supported:<br />
<br />
{|<br />
!Mode<br />
!Description<br />
|-<br />
|deny_all<br />
|No further capabilities are applied to guest users, except ones that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code>.<br />
|-<br />
|static<br />
|A static list of capabilities is applied to guest users via the <code>com.openexchange.share.staticGuestCapabilities</code> property. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.<br />
|-<br />
|inherit<br />
|All capabilities of the user who &quot;created&quot; the guest, i.e. created the link or initially invited somebody, are applied to the guest user. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.<br />
|}<br />
<br />
The mode can be configured via the <code>com.openexchange.share.guestCapabilityMode</code> property in <code>share.properties</code>. This property is config-cascade capable, so it can for example be overridden for certain sets of contexts. The same applies to the <code>com.openexchange.share.staticGuestCapabilities</code> property.<br />
<br />
Due to this configuration mechanism it is possible to increase the user experience for guests and even allow some real collaboration. As an example one could apply the following configuration to allow guests to see preview images of files and edit shared documents with OX Text and OX Spreadsheet:<br />
<br />
<pre>com.openexchange.share.guestCapabilityMode = static<br />
com.openexchange.share.staticGuestCapabilities = document_preview, text, spreadsheet</pre><br />
<br />
=== Anonymous Guest Users ===<br />
<br />
If a &quot;share link&quot; is created, this results in an implicit creation of an anonymous guest user account on the server. The &quot;secret&quot; to access the shared contents is the share token itself that is encoded in the generated share link, so that everybody that knows the share link is able to access the shared contents. Optionally, such an anonymous share link may be secured with an additional PIN code. Guest users will be prompted to enter this PIN code when attempting to access the share.<br />
<br />
To have a strict separation between different shared contents, each time a folder or item is shared using the &quot;Get a link&quot; method, a designated anonymous guest account for this share is used. Consequently, each time such an anonymous share is revoked, this guest account is terminated again with no further delay. Additionally, such an anonymous guest entity can only be applied to the permission set of the folder or item the original link was created for, i.e. it's not possible to add more shared contents to an anonymous guest - in contrast to an invited, named guest user.<br />
<br />
Besides the common restrictions for guest accounts outlined above, the following applies for anonymous guest user accounts:<br />
<br />
* No e-mail address or display name<br />
* No password, if no PIN was assigned by the sharing user<br />
* A password that may only be changed by editing the link, if a PIN code was set<br />
* Anonymous guest users may only receive &quot;read-only&quot; access permissions to the shared item<br />
* Optionally, an expiry date can be applied for an anonymous guest user after which the share link is no longer accessible<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The PIN code for anonymous guest users is stored using symmetrical encryption in the database, therefore, an encryption key needs to be specified via the property <code>com.openexchange.share.cryptKey</code> in <code>share.properties</code><br />
<br />
=== Named Guest Users ===<br />
<br />
Internal users are able to invite a guest user to a folder or item explicitly by specifying the e-mail address of the recipient. Such &quot;named&quot; guest users are internally stored as individual guest users, identified by their e-mail address.<br />
<br />
If data is shared for the first time to the recipient in the context, a new guest user account is provisioned and an initial set of user permissions and capabilities is assigned. In case there are already shares in different contexts to the same recipient (based on his e-mail address), some existing user data like a display name or an assigned password is copied over if a cross-context database is available on the system.<br />
<br />
If the recipient has already been invited from the same or another internal user in the context to another share before, the new share is added to the guest user in a way that the underlying folder- and object permissions are taken over, and the user capabilities getting expanded as needed to cover all modules the shares are located in. Similarly, if a share to a named guest user is revoked and the underlying folder- and object-permissions are removed, the guest user capabilities are updated implicitly to reflect the modules of the remaining shares.<br />
<br />
After the last share to a named guest user has been revoked, the user has no longer access to any data. The account itself gets removed from the context automatically after a configurable expiry time. Additionally, any data that is stored for the guest user in the cross-context database is removed once the guest user has been deleted from all contexts in the system.<br />
<br />
In contrast to an &quot;anonymous&quot; guest user, a named guest user has access to all shared items from a context after logging in, since the permissions get added to an existing guest user account automatically. For entering the web interface, he may use any of the share links that were sent to him in the different notification messages. Those links usually point to an individual share target like a folder or file, but the guest user may navigate to the other shared contents using the folder tree of the web interface in the same way as regular groupware users do. Similarly, if the guest user has access to shares from different modules, the modules can be switched in the web interface as usual.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The timespan after which an unused named guest user should be removed from the system can be configured via <code>com.openexchange.share.cleanup.guestExpiry</code> in <code>share.properties</code> - this value may also be set to <code>0</code> to force an immediate removal<br />
* For the removal of no longer needed guest user accounts, a periodical cleanup task is scheduled based on the interval of <code>com.openexchange.share.cleanup.periodicCleanerInterval</code><br />
* Whether a cross-context database is considered for guest users may be configured via <code>com.openexchange.share.crossContextGuests</code><br />
<br />
== Guest Login &amp; Session Handling ==<br />
<br />
Based on the underlying guest user account, different login operations with different authentication workflows are possible.<br />
<br />
=== Authentication ===<br />
<br />
We have basically three different authentication options for guest users accessing a share, each of them having their own characteristics.<br />
<br />
==== Anonymous ====<br />
<br />
* Access is granted without providing additional authentication information, the knowledge of the link is sufficient<br />
* When accessing the share link, a guest session is spawned implicitly<br />
* Initially supplied cookies are considered to recycle an existing session<br />
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)<br />
<br />
==== Anonymous with PIN ====<br />
<br />
* Access is granted for anonymous guest users providing a password / PIN code<br />
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=anonymous</code><br />
* User can then enter his PIN code, client executes the <code>anonymous_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)<br />
* Password can't be changed by an anonymous user<br />
* Password can be re-constructed / changed by sharing user<br />
<br />
==== Guest without Password ====<br />
<br />
* Access is granted without providing additional authentication information, the knowledge of the guest's individual link is sufficient<br />
* When accessing the share link, a guest session is spawned implicitly<br />
* Exiting cookies are considered to recycle an existing session<br />
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)<br />
* Guest user may choose an individual password at a later stage<br />
<br />
==== Guest with Password ====<br />
<br />
* Access is granted for guest users providing a user name and password.<br />
* Much similar to a regular groupware user<br />
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=guest</code> and <code>login_name=&lt;NAME&gt;</code><br />
* The login name is used to pre-fill the username input<br />
* User can then enter his password, client executes the <code>guest_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)<br />
* Password can be changed by guest user<br />
* Guest user may reset his password if he can't remember<br />
<br />
=== Guest Hostname ===<br />
<br />
For serving shares, a separate guest hostname needs to be configured. This is mainly required to prevent guest- and regular user sessions using the same cookie container when logged in in the same client (otherwise, the cookie holding the alternative session identifier as well as other cookies would get overwritten concurrently). Additionally, this allows to have separate entry points to the web client for guest- and regular users. <br />
<br />
The hostname for guests is used when generating external share links, as well as at other locations where hyperlinks are constructed in the context of guest users. Usually, the guest hostname refers to a separate subdomain of the installation like <code>share.example.com</code>, and is defined as an additional named virtual host pointing to the web client's document root in the webserver's configuration. <br />
<br />
Once the webserver configuration is done and the web client is accessible using the guest hostname, this hostname needs to be specified in the backend configuration, too. In simple scenarios, where a fixed guest hostname should be used for the installation, this can be done statically in a configuration file. This setting may also be overridden per context via the Config Cascade. In case a dedicated hostname service is installed (for example <code>open-xchange-hostname-ldap</code>), this hostname service is also supposed to supply the guest hostname. <br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The guest hostname may be specified via <code>com.openexchange.share.guestHostname</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The guest hostname may also be supplied via dedicated hostname services like <code>open-xchange-hostname-config-cascade</code> or <code>open-xchange-hostname-ldap</code><br />
* For test purposes, guests may also access the web interface using the same host as regular users do, however, this might lead to unexpected results (missing images, sessions timing out, auto-login malfunction...)<br />
<br />
=== Cookies ===<br />
<br />
Guest sessions basically make use of the same cookies as regular user sessions do. This includes the JSESSONID cookie for the JVM route, as well as the <code>open-xchange-secret-&lt;hash&gt;</code> and <code>open-xchange-public-session-&lt;hash&gt;</code> cookies. Additionally, if configured, the client may also issue a <code>store</code> request to persist the open-xchange-session-<hash> cookie. This cookie may then be used to auto-login the guest client into the previously used session if it is still valid.<br />
<br />
Besides the common cookies, another special cookie is set: <code>open-xchange-share-&lt;hash&gt;</code>. The value contains the unique share token bound to the guest user accessing the share. here, the cookie hash is calculated as it's done for ordinary sessions, so that there can only be one <code>open-xchange-share-&lt;hash&gt;</code> cookie in a client at the same time. Whenever an auto-login request is issued by the client, the server checks for the existence of this &quot;share&quot; cookie, and, once recognized and checked for validity, it will try to perform the auto-login for an existing guest session first, i.e. using the session cookie based on the special guest hash calculation outlined above. Otherwise, the common auto-login process takes place. The &quot;share&quot; cookie is removed once the guest session terminates, i.e. the guest user logs out.<br />
<br />
Since guest users access the web interface on a separate (sub)domain (see [[#Guest_Hostname|Guest Hostname]] above for details), guest session cookies won't interfere with cookies of a regular session on the same client. This allows to use the regular user session as well as one or more guest sessions in parallel - e.g. if the sharing user quickly wants to check how the contents appear for the guest user after generating a share link.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Whether guest sessions are enabled for auto-login is configurable via the property <code>com.openexchange.share.autoLogin</code> in <code>share.properties</code><br />
* By default, the cookie TTL for guest sessions is inherited from the TTL for cookies of regular sessions as defined by <code>com.openexchange.cookie.ttl</code> - this default may be overridden by defining a timespan at <code>com.openexchange.share.cookieTTL</code><br />
<br />
=== Login Modes ===<br />
<br />
When accessing a share link, one of the following login modes is triggered to acquire a session and forward the client to the share target. The executed login operation and redirect depends on the authentication mode of underlying guest account, the share target iteself, and the client accessing the share.<br />
<br />
==== Redirect to Target ====<br />
<br />
In case a share is accessible without providing credentials, the client is redirected to the share target directly, i.e. without prompting for a username or password. By default, the client is redirected to the target in the App Suite web interface by responding the <code>GET</code> request to the share link with <code>HTTP 302</code>, and a location header like the following:<br />
<br />
<code>Location: /appsuite/ui#!&amp;session=80c711019d6f48b5bec9cd82758e3308&amp;store=true&amp;user=&amp;user_id=642&amp;context_id=1&amp;m=files&amp;f=41042</code><br />
<br />
The session for the guest user is created implicitly in the backend after checking the share link's validity, and the client is instructed to store appropriate cookies in the redirect response, including the &quot;share&quot; cookie:<br />
<br />
<code>Set-Cookie: open-xchange-secret-aNobP2G9wLHJ6sMr7vtTA=38ee770d6e4f42ab8366d91db3279931; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=cae6a3e712ac429e9da9194abd389cb3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ad50ac00418fbcdad50ac1418f94fb181d51b8fa7b2bde3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br />
<br />
==== Redirect to Login Screen ====<br />
<br />
If additional credentials, i.e. an additional PIN code or username/password combination, are required to access a share target, and no &quot;special client&quot; like an iCal consumer is detected by the backend, the client is redirected to the login screen of the app suite webinterface. The GET request to the share link is answered with statuscode HTTP 302, and a location header depending on the required credentials to access the share.<br />
<br />
If the share ought to be accessed anonymously, but protected by a PIN code, a location like the following is added to the response header:<br />
<br />
<code>Location: /appsuite/ui#!&amp;share=08b4b6110151f1bd7d4b610151f0405d9fc8bb89a887f04e&amp;login_type=anonymous&amp;message_type=INFO&amp;message=Tony%20Parker%20has%20shared%20the%20folder%20%22Pictures%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&amp;target=151ebb38</code><br />
<br />
For shares to dedicated guest users identified by their e-mail address, the redirect location looks like follows:<br />
<br />
<code>Location: /appsuite/ui#!&amp;share=4ac9eb590f9ca4d2ac9eb58f9ca611ec9b4f4638d288c8c0&amp;login_type=guest&amp;message_type=INFO&amp;message=Tony%20Parker%20has%20shared%20the%20file%20%22Agenda.pdf%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&amp;login_name=ray%40example.com&amp;target=4444cbc7</code><br />
<br />
The redirect response already contains the <code>Set-Cookie</code> header for the JVM route. On the redirect target, the client should request the PIN code or password from the user, and then issue a special login request, supplying the share token and optional target from the URL parameters, and the password as URL encoded form data in the request body, similar to the usual login request via POST. After successful authentication, the login response includes, along with the common login response properties like the session identifier, information about the share target being accessed:<br />
<br />
<code>{&quot;session&quot;:&quot;b89af2c2ce494ce4b4573c0632b48e89&quot;,&quot;user&quot;:&quot;ray@example.com&quot;,&quot;user_id&quot;:660,&quot;context_id&quot;:1,&quot;locale&quot;:&quot;en_US&quot;,&quot;module&quot;:&quot;files&quot;,&quot;folder&quot;:&quot;10&quot;,&quot;item&quot;:&quot;10/456398&quot;, ... }</code><br />
<br />
Additionally, the client is instructed to store the secret cookies:<br />
<br />
<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ac9eb590f9ca4d5ac9eb58f9ca641ec9b4f4638d288c8a0; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-secret-MBIRg9bJBLduCcosqQBCw=70187de16f844be6880c18be373b953d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=4e797a59758a4dd7b763912472ccf26d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br />
<br />
Afterwards, the client is able to use the session to access the share target as usual.<br />
<br />
=== Session Lifecycle ===<br />
<br />
Generally, guest sessions on the server are treated just like the sessions of ordinary users. Especially, guest sessions are also held in the local session containers of the backend host they're associated with. However, by default guest sessions are marked as <code>transient</code>, i.e. they are not moved to the long-term session containers, nor they are put into the distributed session storage.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Guest sessions are also accounted in the monitoring outputs (e.g. in the sessions per container graphs)<br />
* The <code>transient</code> handling of guest sessions may be changed via the property <code>com.openexchange.share.transientSessions</code> in <code>share.properties</code><br />
<br />
=== Logout ===<br />
<br />
Guest sessions are terminated once a logout request is issued by the client, i.e. the user clicks the &quot;Logout&quot; button in the web interface, just like it is done for regular sessions. Additionally, guest sessions expire in the backend when not being used for a while, the actual timeout depends on the configured default session lifetime and whether they are treated as &quot;transient&quot; or not, as explained above.<br />
<br />
Since guest users are not able to use the default login page for regular users, a custom logout location for guest users should be specified where guest users are taken to after clicking logout explicitly, or if their session expired.<br />
<br />
If a share is consumed &quot;directly&quot;, e.g. by downloading the binary contents of a file share directly (see [[#Consuming_Shares|Consuming Shares]] for details), the guest sessions is terminated instantly after serving the request.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The logout location for guest accounts can be customized via <code>guestLogoutLocation</code> in the file <code>as-config.yml</code> (see file <code>as-config-default.yml</code> for an example)<br />
<br />
== Share Notifications ==<br />
<br />
With the new sharing concept, notification mails can be sent out to the permission entities (i.e. internal or guest users) of folders or items. Mechanisms exist to send out such mails implicitly or explicitly. Notifications are sent out implicitly, if externals are invited as guests and can also be sent out for internal invitations, if configured so. The client (e.g. App Suite UI) decides on its own whether implicit notifications shall be sent when updating a folders or items permissions. Besides there are separate API calls for sending out notification messages explicitly. Its on the client to provide this functionality to its users. This makes it possible to re-send a link to a folder or item to an existing permission entity.<br />
<br />
Sending out links to shared folders and items is not the only case for notification messages, it can also be necessary to send out system notifications to guest users. Currently this is the case when a guest user secured his account with a password and needs to reset that password, because he cannot remember.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* A special transport must be configured for system notifications and cases where the sharing user has no configured webmail account. This transport is configured in <code>noreply.properties</code>. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.<br />
* It is possible to disable the implicit notification of internal users about shared folders or items at all by setting <code>com.openexchange.share.notifyInternal</code> in <code>share.properties</code> to <code>false</code>.<br />
* The layout of notifications mails can be changed via <code>as-config.yml</code>. All available properties are defined and explained in <code>as-config-defaults.yml</code>.<br />
<br />
== API Access ==<br />
<br />
From a client's point of view, guest users basically don't differ from regular users, although they usually have limited capabilities, for example no mail access or no personal folders. However, all those differences are reflected within the regular permission- and capability-concepts, so that existing clients, once the guest user is authenticated and has a valid session, continue to work transparently, and use the same API calls as with a regular groupware user.<br />
<br />
To create or manage shares and guest users, the HTTP API has been extended at various locations. The following list gives an overview about the changes, derived from the corresponding software change requests.<br />
<br />
=== Format change for object identifiers of the default &quot;infostore&quot; account ===<br />
<br />
As preparation for individual object permissions where a file can be accessed from different folder &quot;views&quot;, the object IDs for documents in the default &quot;infostore&quot; file storage account will get enhanced with the prefixing folder ID.<br />
<br />
The identifiers will now be of format <code>&lt;some numbers&gt;/&lt;more numbers&gt;</code>. Object identifiers are already of type <code>String</code>, so this change should usually be transparent to clients. However, there may be some clever clients out there that for example tried to interpret the string of numerical characters as number, so client developers should double-check their implementation for compatibility. They most likely would run into trouble when coping with non-infostore file storages anyway.<br />
<br />
=== Object permissions for files ===<br />
<br />
In order to define permissions on object-level, a new property <code>object_permissions</code> for objects of type <code>infoitem</code> is introduced. Each time the underlying folder permissions are not sufficient to access an item, those object permissions are taken into account. Object permissions are stored as an array of Object Permission objects as defined below within the detailed infoitem data, the column ID is <code>108</code>.<br />
<br />
Details about the JSON structure are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionFlags HTTP API: Object Permission Flags]<br />
<br />
=== New field for &quot;user&quot; data: &quot;guest_created_by&quot; ===<br />
<br />
A new property has been introduced for users that needs to be exposed in our HTTP API, too. The following property is added to the detailed user data object:<br />
<br />
* ID: 616<br />
* Name: guest_created_by<br />
* Type: Number<br />
* Value: Contains the ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users<br />
<br />
The property is read-only and can't be removed or set by clients.<br />
<br />
See also:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedUserData HTTP API: Detailed User Data]<br />
<br />
=== Extend folder- and object permissions for addressing external guests ===<br />
<br />
For sharing files- or folders to external guests, the folder- and object permission objects are extended with additional properties. Those extended properties can be set during creation or update of the parent folder or file. The underlying shares and guest user entities for the referenced recipients are created automatically along with folder/file creation/update. Afterwards, the external recipients appear as regular &quot;user&quot; entities in the permission arrays in subsequent &quot;get&quot; requests.<br />
<br />
Details about the extended JSON structure are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#PermissionObject HTTP API: Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]<br />
<br />
=== New Ajax module: share/management ===<br />
<br />
To work with shares, a new Ajax module is introduced.<br />
<br />
The available actions in the module are described at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Module_.22share.2Fmanagement.22_.28preliminary.2C_available_with_v7.8.0.29 HTTP API: Module share management]<br />
<br />
=== New column &quot;shareable&quot; in detailed infoitem data ===<br />
<br />
Clients want to know quickly if an infostore item is shareable or not. A new (read-only) property named <code>shareable</code> of type Boolean with column identifier <code>109</code> is introduced for &quot;detailed infoitem data&quot;. If &quot;true&quot;, the can be considered as shareable, i.e. the item's object permissions may be adjusted by the user.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]<br />
<br />
=== New action &quot;shares&quot; in module folder ===<br />
<br />
To provide an overview of all folders of a certain modules that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>folders</code>. It returns all personal folders of a certain module that are shared to other entities.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared folders]<br />
<br />
=== New action &quot;shares&quot; in module infostore ===<br />
<br />
To provide an overview of all files that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>infostore</code>. It returns all personal files that are shared to other entities.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared infoitems]<br />
<br />
=== New fields to retrieve extended permissions of files and folders ===<br />
<br />
Clients would like to have more details about permission entities folders directly. A new read-only property named <code>com.openexchange.share.extendedPermissions</code> is introduced for &quot;Detailed folder data&quot;, with column identifier <code>3060</code>. It basically contains the same as the regular <code>permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.<br />
<br />
Similarly, a new read-only property named <code>com.openexchange.share.extendedObjectPermissions</code> is introduced for &quot;Detailed infoitem data&quot;, with column identifier <code>7010</code>. It basically contains the same as the regular <code>object_permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.<br />
<br />
Further information about the JSON structure is available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedPermissionObject HTTP API: Extended Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedObjectPermissionObject HTTP API: Extended Object Permission Object]<br />
<br />
== Consuming Shares ==<br />
<br />
Depending on the shared contents and the requesting user agent, shares may be consumed in a couple of different ways. The concrete response to a request to the share URL is evaluated by the share servlet in the backend.<br />
<br />
=== App Suite ===<br />
<br />
The default handling for all shares is forwarding them to the App Suite web interface, where the shared contents are made available through the existing client. Based on the underlying guest account, the client is either forwarded to the login prompt, or taken directly to the share target if no credentials need to be provided. This process is described in more detail at [[#Guest_Login_&_Session_Handling|Guest Login &amp; Session Handling]].<br />
<br />
=== Direct Download ===<br />
<br />
Shares to a single file may also be downloaded directly by clients, without opening them in the web interface first. This is indicated by an additional parameter appended to the plain share link, and can be specified in the following ways:<br />
<br />
* Append <code>dl</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?dl=true</code><br />
* Specify <code>delivery</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?delivery=download</code><br />
<br />
If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an &quot;anonymous&quot; share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like &quot;Guest&quot;.<br />
<br />
=== Get iCal ===<br />
<br />
Shares to a single calendar- or task-folder may also be downloaded directly by clients as iCal files, without opening them in the web interface first. This standard format allows to consume event data directly using various calendaring clients, which often can be configured to subscribe an external calendar source.<br />
<br />
Once a share link to a calendar- or task-folder is requested by the client, the <code>Accept</code>- and <code>User-Agent</code> headers of the request are evaluated. If the <code>Accept</code> header is either set to <code>text/calendar</code> or <code>text/iCal</code>, or if the <code>User-Agent</code> header denotes a well-known client like Microsoft Outlook or Mozilla Thunderbird w/ Lightning, the contents of the shared folder are converted to an iCal file that is directly written back in the response.<br />
<br />
To force the iCal output, an additional parameter may be appended to the plain share link:<br />
<br />
* Append <code>ical</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?ical=true</code><br />
<br />
If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an &quot;anonymous&quot; share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like &quot;Guest&quot;.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The interval of task- and appointment data considered for conversion to iCal can be adjusted via <code>com.openexchange.share.handler.iCal.futureInterval</code> and <code>com.openexchange.share.handler.iCal.pastInterval</code> in configuration file <code>share.properties</code><br />
<br />
== Cross-context functionality ==<br />
<br />
As already mentioned in previous sections the administrator is able to configure if guests should be handled per context (default) or server wide by using the configuration parameter <code>com.openexchange.share.crossContextGuests</code>.<br />
<br />
If set to <code>true</code> the guests email address is used to recognize if there is already a registered user with the given address and aligns the stored password to the already existing guest user. In addition to the password (which is the most important parameter this feature is about) even the users contact data gets synchronized.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* To handle user and contact data across contexts boundaries the feature has to be enabled before a guest receives the first share. Guests that receive shares before the activation cannot be considered within the alignment process. Only latter shares will be considered.<br />
* At the moment this feature does only sync user and contact related data (no shared content). If the user got two shares from different contexts he will only see shares related to the given link.<br />
<br />
== Publish/Subscribe vs. Sharing ==<br />
<br />
The upcoming sharing features are going to replace the previously used OXMF &quot;publications&quot;, allowing guest users to interact with the shared data in the same way as regular groupware users do. However, since the underlying concepts and their technical realization are completely different, a seamless migration between publications and shares is not possible without some drawbacks.<br />
<br />
The following list gives an overview of the main discrepancies:<br />
<br />
* Custom templates for OXMF publication targets<br />An adminsitrator/admin may have defined some custom publication targets that are using the published data in a special way. While shares would still make all the data available (mainly via the web interface), this would only be a drop-in replacement for the ordinary &quot;view the publication in a browser&quot; use case, but not for anything beyond that scope.<br />
* Subscribe of publications<br />Publications from one user can be added to another user's groupware using the &quot;subscribe&quot; functionality, making use of the embedded microformat data of publications (OXMF). For sharing, we will not have a similar feature in the first iteration, so migrating an existing publication to a share would also stop it from being subscribable.<br />
* Deep links to download files of publications<br />Files behind an infostore publication were accessible behind a static URL, which would theoretically allow them to be requested independently of the parent publication (e.g. images linked from an external website). While the entry URL to a publication would be mappable to a corresponding share URL, converting existing publications to shares would at least break such deep links.<br />
<br />
Because of the above points and the whole different concept, we do not migrate existing publications to shares. Instead, the default behavior will be:<br />
<br />
* No new OXMF publications or subscriptions can be created by default<br />
* The web client does no longer give the option to publish or subscribe in the OXMF format<br />
* Existing OXMF publications / subscriptions can't be updated<br />
* Existing OXMF publications continue to work as is, including associated subscriptions<br />
* Yet it's still possible to delete existing publications and subscriptions<br />
* Therefore, the menu section &quot;Publications and Subscriptions&quot; will still be available (if there's at least one publication or subscription)<br />
<br />
Exceptions to these rules cover special internal subscriptions to 3rd party services like addressbooks from LinkedIn or Xing, as well as the auto-publish feature of mail attachments exceeding a specific size.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The possibility to create/update OXMF publications via HTTP-API may be configured via <code>com.openexchange.publish.createModifyEnabled</code> in file <code>publications.properties</code><br />
* The possibility to create/update OXMF subscriptions via HTTP-API may be configured via <code>com.openexchange.subscribe.microformats.createModifyEnabled</code> in file <code>microformatSubscription.properties</code><br />
<br />
<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode&diff=21653AppSuite:Sharing and Guest Mode2016-03-16T14:41:08Z<p>Steffen.templin: /* Required Permissions and Capabilities */</p>
<hr />
<div><div class="title">Sharing and Guest Mode</div><br />
<br />
{{VersionFrom|7.8.0}}<br />
<br />
__TOC__<br />
<br />
== Introduction ==<br />
<br />
Starting with v7.8.0, the Open-Xchange server comes with a whole new concept to share contents with external people, allowing guest users to interact with the shared data in the same way as regular groupware users do. This article describes the underlying technical implications and outlines the different use cases.<br />
<br />
The main idea behind the new sharing concept is that guest users, i.e. external users without a regular account on the server, should be able to access the shared contents using the existing interfaces, especially the App Suite web interface. On the one hand, this includes consuming the shared data using the App Suite's advanced media viewing capabilities. On the other hand, this enables guests to edit existing as well as to create or upload new content in the groupware. Even real-time collaboration between internal users and guests in OX Documents is possible.<br />
<br />
The following chapters cover different topics regarding sharing and guest users and try to describe some technical background and impact where hosters, administrators or integrators might be interested in.<br />
<br />
== Creating Shares ==<br />
<br />
Basically, creating a share means adding an additional permission entity to the shared folder or item. Previously, this was only possible for &quot;internal&quot; entities, i.e. regular users or user groups. Now, the underlying permission system has been extended to support external entities, which can be either invited guest users, or special &quot;anonymous&quot; guest users who access a shared folder or item via a secret link. Anonymous and invited guest users are explained in more detail below.<br />
<br />
Sharing is available for the groupware modules Calendar, Contacts, Tasks and Drive (a.k.a. Infostore/Files). While the latter one also allows "writable" access for invited guest users, folders from the Calendar, Contacts and Tasks module may only be published in "read-only" mode to external guests.<br />
<br />
=== Invite Guests ===<br />
<br />
To share something to a guest user, it's possible to just add the e-mail address of the invitee as new permission entity for files and folders. The middleware then takes care to provision a new or reuse an existing account for the guest user, and equips him with the required permissions for accessing the contents. So, from a client's point of view, sharing something to a guest user is mostly the same process as sharing something to an internal user or group.<br />
<br />
=== Share Links ===<br />
<br />
Besides explicitly inviting a guest user to a share, it's also possible to just get a secret link for a folder or item. This will result in an additional &quot;anonymous&quot; guest entity in the permissions of the shared object, and will grant any user with the corresponding share link access the shared contents. To simplify the creation of share links, the clients will offer an additional &quot;wizard&quot; to quickly get a share link for a folder or item. Unlike invited guests which behave much like internal users, anonymous guest entities are strictly bound to the underlying folder or item, i.e. there is at most one anonymous permission entity per file or folder, as well as an anonymous permission entity can only be used for only once.<br />
<br />
=== Required Permissions and Capabilities ===<br />
<br />
Whether a user is allowed to create share links, invite external guests, or internal groups or users, depends on the following module access permissions and capabilities. Please note that share links no longer require <code>read_create_shared_folders</code> since Open-Xchange v7.8.1; this restriction was removed in order to allow simple publications also for non-groupware accounts, e.g. as defined by the <code>pim</code> or <code>pim_infostore</code> module access combinations.<br />
<br />
* Create, update & remove share links ''(in v7.8.0)'': <code>read_create_shared_folders</code>, <code>share_links</code><br />
* Create, update & remove share links ''(in v7.8.1 and above)'': <code>share_links</code><br />
* Add, update or remove internal users and group permissions: <code>read_create_shared_folders</code><br />
* Add, update or remove external guest permissions: <code>read_create_shared_folders</code>, <code>invite_guests</code><br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Existing shares for a guest user or context may be listed using the commandline utility <code>listshares</code><br />
* The ability to create share links may be controlled via <code>com.openexchange.capability.share_links</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The ability to invite guest users may be controlled via <code>com.openexchange.capability.invite_guests</code>, either globally in the configuration file <code>permissions.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The number of allowed share links per user may be specified via <code>com.openexchange.quota.share_links</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The number of allowed guest invitations per user may be specified via <code>com.openexchange.quota.invite_guests</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
<br />
== Removing Shares ==<br />
<br />
The lifetime of shares is implicitly bound to the lifetime of the associated permission of the guest user entity. So, once a permission entity pointing to a (named or anonymous) guest user account is removed from the parent folder or item, this also leads to the removal of the associated share itself. Afterwards, the contents are no longer accessible for the guest user. For shares that were created with a specific expiry date, it is ensured that they can no longer be accessed via their share link after expiring. Additionally, expired shares are cleaned up periodically within a background task.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Shares may be revoked manually using the commandline utility <code>removeshares</code><br />
* The interval of the periodic cleanup task can be controlled via <code>com.openexchange.share.cleanup.periodicCleanerInterval</code> in <code>share.properties</code><br />
<br />
== Share Links &amp; Tokens ==<br />
<br />
Shares are accessed with a hyperlink that contains the so-called share &quot;token&quot;. This 24-byte token uniquely identifies the associated guest account on the system, and carries enough randomness that it can't be guessed. Explicitly invited guest users receive this hyperlink in the invitation mail to a share, while in case of an &quot;anonymous&quot; share where just the link itself was generated, it's up to the sharing user to distribute the link on his own. Besides the token, a share link may contain an additional path that points to the concrete folder and item, which just aids to jump to the shared item in the web interface directly. The following shows an example of a share link:<br />
<br />
<code>https://share.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/1/2/ODAxMDY</code><br />
<br />
If a guest user has been invited to more than one share in a context (based on his e-mail address), his individual share token remains equal, so that he will have access to all shared contents in the web interface after following any of the share links he received. However, the additional &quot;path&quot; still points to the concrete item. When inviting more than one guest user to the same share, each recipient will get his own individual share link.<br />
<br />
Once the share URL is requested from the server, the associated guest account is looked up and, depending of the guest type, the request is redirected to a specific login screen or directly into the App Suite web interface. More details regarding the different login modes are described at [[#Guest_Login_&_Session_Handling|Guest Login &amp; Session Handling]].<br />
<br />
After a share has been revoked (either explicitly, by removing the permission, or if the share is expired), share links can't be accessed any longer, and, after the last share for the guest user was removed, the guest account is removed from the system automatically.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The share token is stored as user attribute <code>com.openexchange.shareBaseToken</code> in the corresponding guest user account<br />
* The target database schema for a share and the associated guest account is extracted from the context identifier encoded in the share token<br />
<br />
== Guest Users ==<br />
<br />
As outlined above, guest users are created on demand once something is being shared. We basically distinguish between two types of guest users: Those that were invited explicitly by the sharing user, or &quot;anonymous&quot; guest users that are able to access by visiting the share link. Access for the latter one may optionally be secured with a fixed PIN code.<br />
<br />
For both kinds of guest users, a corresponding user account is provisioned dynamically on the system once a new share is created. Such a guest account is handled much similar as an account for a regular user, with the following main exceptions:<br />
<br />
* No access to the &quot;Mail&quot; module<br />
* No personal folders<br />
* No access to the &quot;Portal&quot;<br />
* No access to the global address book<br />
* Module access is restricted to only include modules from the actual shares<br />
<br />
All those restrictions are configured and enforced using the built-in mechanisms of the Open-Xchange Server, i.e. by a reduced set of capabilities (i.e. module permissions), or by selectively set permission bits in the folder tree for the virtual guest group. This ensures that guest users are only able to access things they explicitly have been invited to, as well as a transparent handling of guest accounts within all subsystems.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Guest users are stored much similar as regular users in the database (tables <code>user</code>, <code>prg_contacts</code>, <code>user_attribute</code>, <code>user_configuration</code>)<br />
* Additionally, the identifier of the user who (initially) created the guest account is stored in <code>user.guestCreatedBy</code>, i.e. if this column is not <code>0</code>, this entry refers to a guest user<br />
* All service calls and APIs that list or search users have been adjusted to be &quot;guest-aware&quot;, i.e. by default, guests users are not included in the output, yet may be included explicitly with additional parameters (namely <code>includeGuests</code> and <code>excludeUsers</code>)<br />
* Service calls and APIs that request data explicitly based on an entity's identifier are also working with guest users, i.e. if a specific idnetifier points to a guest, then the referenced guest data is returned<br />
<br />
=== Capabilities ===<br />
<br />
Guest users always have the <code>guest</code> capability set. Besides they are generally configured with a limited permission set, that allows them just to work with their shared items. This permission set includes:<br />
<br />
{|<br />
!Permission<br />
!Capability<br />
!Details<br />
|-<br />
|<code>deniedportal</code><br />
|<br />
|No <code>portal</code> capability<br />
|-<br />
|<code>editpublicfolders</code><br />
|<code>edit_public_folders</code><br />
|<br />
|-<br />
|<code>readcreatesharedfolders</code><br />
|<code>read_create_shared_folders</code><br />
|<br />
|-<br />
|<code>editpassword</code><br />
|<code>edit_password</code><br />
|Only for invited guests, not links<br />
|}<br />
<br />
Additionally, for every module the guest is having shared items in, the according module permission is granted, e.g. a shared drive folder results in permission <code>infostore</code> and the according capability. Guest users are never allowed to share folders or items on their own, i.e. the capabilities <code>share_links</code> and <code>invite_guests</code> can never be set.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
This limited capability set can be extended by configuration. Currently three modes are supported:<br />
<br />
{|<br />
!Mode<br />
!Description<br />
|-<br />
|deny_all<br />
|No further capabilities are applied to guest users, except ones that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code>.<br />
|-<br />
|static<br />
|A static list of capabilities is applied to guest users via the <code>com.openexchange.share.staticGuestCapabilities</code> property. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.<br />
|-<br />
|inherit<br />
|All capabilities of the user who &quot;created&quot; the guest, i.e. created the link or initially invited somebody, are applied to the guest user. Additionally capabilities that have been explicitly set for the guest user via <code>changeuser --capabilities-to-add</code> are applied.<br />
|}<br />
<br />
The mode can be configured via the <code>com.openexchange.share.guestCapabilityMode</code> property in <code>share.properties</code>. This property is config-cascade capable, so it can for example be overridden for certain sets of contexts. The same applies to the <code>com.openexchange.share.staticGuestCapabilities</code> property.<br />
<br />
Due to this configuration mechanism it is possible to increase the user experience for guests and even allow some real collaboration. As an example one could apply the following configuration to allow guests to see preview images of files and edit shared documents with OX Text and OX Spreadsheet:<br />
<br />
<pre>com.openexchange.share.guestCapabilityMode = static<br />
com.openexchange.share.staticGuestCapabilities = document_preview, text, spreadsheet</pre><br />
<br />
=== Anonymous Guest Users ===<br />
<br />
If a &quot;share link&quot; is created, this results in an implicit creation of an anonymous guest user account on the server. The &quot;secret&quot; to access the shared contents is the share token itself that is encoded in the generated share link, so that everybody that knows the share link is able to access the shared contents. Optionally, such an anonymous share link may be secured with an additional PIN code. Guest users will be prompted to enter this PIN code when attempting to access the share.<br />
<br />
To have a strict separation between different shared contents, each time a folder or item is shared using the &quot;Get a link&quot; method, a designated anonymous guest account for this share is used. Consequently, each time such an anonymous share is revoked, this guest account is terminated again with no further delay. Additionally, such an anonymous guest entity can only be applied to the permission set of the folder or item the original link was created for, i.e. it's not possible to add more shared contents to an anonymous guest - in contrast to an invited, named guest user.<br />
<br />
Besides the common restrictions for guest accounts outlined above, the following applies for anonymous guest user accounts:<br />
<br />
* No e-mail address or display name<br />
* No password, if no PIN was assigned by the sharing user<br />
* A password that may only be changed by editing the link, if a PIN code was set<br />
* Anonymous guest users may only receive &quot;read-only&quot; access permissions to the shared item<br />
* Optionally, an expiry date can be applied for an anonymous guest user after which the share link is no longer accessible<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The PIN code for anonymous guest users is stored using symmetrical encryption in the database, therefore, an encryption key needs to be specified via the property <code>com.openexchange.share.cryptKey</code> in <code>share.properties</code><br />
<br />
=== Named Guest Users ===<br />
<br />
Internal users are able to invite a guest user to a folder or item explicitly by specifying the e-mail address of the recipient. Such &quot;named&quot; guest users are internally stored as individual guest users, identified by their e-mail address.<br />
<br />
If data is shared for the first time to the recipient in the context, a new guest user account is provisioned and an initial set of user permissions and capabilities is assigned. In case there are already shares in different contexts to the same recipient (based on his e-mail address), some existing user data like a display name or an assigned password is copied over if a cross-context database is available on the system.<br />
<br />
If the recipient has already been invited from the same or another internal user in the context to another share before, the new share is added to the guest user in a way that the underlying folder- and object permissions are taken over, and the user capabilities getting expanded as needed to cover all modules the shares are located in. Similarly, if a share to a named guest user is revoked and the underlying folder- and object-permissions are removed, the guest user capabilities are updated implicitly to reflect the modules of the remaining shares.<br />
<br />
After the last share to a named guest user has been revoked, the user has no longer access to any data. The account itself gets removed from the context automatically after a configurable expiry time. Additionally, any data that is stored for the guest user in the cross-context database is removed once the guest user has been deleted from all contexts in the system.<br />
<br />
In contrast to an &quot;anonymous&quot; guest user, a named guest user has access to all shared items from a context after logging in, since the permissions get added to an existing guest user account automatically. For entering the web interface, he may use any of the share links that were sent to him in the different notification messages. Those links usually point to an individual share target like a folder or file, but the guest user may navigate to the other shared contents using the folder tree of the web interface in the same way as regular groupware users do. Similarly, if the guest user has access to shares from different modules, the modules can be switched in the web interface as usual.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The timespan after which an unused named guest user should be removed from the system can be configured via <code>com.openexchange.share.cleanup.guestExpiry</code> in <code>share.properties</code> - this value may also be set to <code>0</code> to force an immediate removal<br />
* For the removal of no longer needed guest user accounts, a periodical cleanup task is scheduled based on the interval of <code>com.openexchange.share.cleanup.periodicCleanerInterval</code><br />
* Whether a cross-context database is considered for guest users may be configured via <code>com.openexchange.share.crossContextGuests</code><br />
<br />
== Guest Login &amp; Session Handling ==<br />
<br />
Based on the underlying guest user account, different login operations with different authentication workflows are possible.<br />
<br />
=== Authentication ===<br />
<br />
We have basically three different authentication options for guest users accessing a share, each of them having their own characteristics.<br />
<br />
==== Anonymous ====<br />
<br />
* Access is granted without providing additional authentication information, the knowledge of the link is sufficient<br />
* When accessing the share link, a guest session is spawned implicitly<br />
* Initially supplied cookies are considered to recycle an existing session<br />
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)<br />
<br />
==== Anonymous with PIN ====<br />
<br />
* Access is granted for anonymous guest users providing a password / PIN code<br />
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=anonymous</code><br />
* User can then enter his PIN code, client executes the <code>anonymous_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)<br />
* Password can't be changed by an anonymous user<br />
* Password can be re-constructed / changed by sharing user<br />
<br />
==== Guest without Password ====<br />
<br />
* Access is granted without providing additional authentication information, the knowledge of the guest's individual link is sufficient<br />
* When accessing the share link, a guest session is spawned implicitly<br />
* Exiting cookies are considered to recycle an existing session<br />
* The login screen is skipped, we'll redirect to the module/folder/item directly (using appropriate URL fragments)<br />
* Guest user may choose an individual password at a later stage<br />
<br />
==== Guest with Password ====<br />
<br />
* Access is granted for guest users providing a user name and password.<br />
* Much similar to a regular groupware user<br />
* When accessing the share link, the client is redirected to the login screen of the webinterface, using <code>login_type=guest</code> and <code>login_name=&lt;NAME&gt;</code><br />
* The login name is used to pre-fill the username input<br />
* User can then enter his password, client executes the <code>guest_login</code> method, server authenticates, sends back a login response containing the target in the app suite webinterface (module/folder/item)<br />
* Password can be changed by guest user<br />
* Guest user may reset his password if he can't remember<br />
<br />
=== Guest Hostname ===<br />
<br />
For serving shares, a separate guest hostname needs to be configured. This is mainly required to prevent guest- and regular user sessions using the same cookie container when logged in in the same client (otherwise, the cookie holding the alternative session identifier as well as other cookies would get overwritten concurrently). Additionally, this allows to have separate entry points to the web client for guest- and regular users. <br />
<br />
The hostname for guests is used when generating external share links, as well as at other locations where hyperlinks are constructed in the context of guest users. Usually, the guest hostname refers to a separate subdomain of the installation like <code>share.example.com</code>, and is defined as an additional named virtual host pointing to the web client's document root in the webserver's configuration. <br />
<br />
Once the webserver configuration is done and the web client is accessible using the guest hostname, this hostname needs to be specified in the backend configuration, too. In simple scenarios, where a fixed guest hostname should be used for the installation, this can be done statically in a configuration file. This setting may also be overridden per context via the Config Cascade. In case a dedicated hostname service is installed (for example <code>open-xchange-hostname-ldap</code>), this hostname service is also supposed to supply the guest hostname. <br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The guest hostname may be specified via <code>com.openexchange.share.guestHostname</code>, either globally in the configuration file <code>share.properties</code>, or on a more fine-granular level through the [https://oxpedia.org/wiki/index.php?title=ConfigCascade Config Cascade]<br />
* The guest hostname may also be supplied via dedicated hostname services like <code>open-xchange-hostname-config-cascade</code> or <code>open-xchange-hostname-ldap</code><br />
* For test purposes, guests may also access the web interface using the same host as regular users do, however, this might lead to unexpected results (missing images, sessions timing out, auto-login malfunction...)<br />
<br />
=== Cookies ===<br />
<br />
Guest sessions basically make use of the same cookies as regular user sessions do. This includes the JSESSONID cookie for the JVM route, as well as the <code>open-xchange-secret-&lt;hash&gt;</code> and <code>open-xchange-public-session-&lt;hash&gt;</code> cookies. Additionally, if configured, the client may also issue a <code>store</code> request to persist the open-xchange-session-<hash> cookie. This cookie may then be used to auto-login the guest client into the previously used session if it is still valid.<br />
<br />
Besides the common cookies, another special cookie is set: <code>open-xchange-share-&lt;hash&gt;</code>. The value contains the unique share token bound to the guest user accessing the share. here, the cookie hash is calculated as it's done for ordinary sessions, so that there can only be one <code>open-xchange-share-&lt;hash&gt;</code> cookie in a client at the same time. Whenever an auto-login request is issued by the client, the server checks for the existence of this &quot;share&quot; cookie, and, once recognized and checked for validity, it will try to perform the auto-login for an existing guest session first, i.e. using the session cookie based on the special guest hash calculation outlined above. Otherwise, the common auto-login process takes place. The &quot;share&quot; cookie is removed once the guest session terminates, i.e. the guest user logs out.<br />
<br />
Since guest users access the web interface on a separate (sub)domain (see [[#Guest_Hostname|Guest Hostname]] above for details), guest session cookies won't interfere with cookies of a regular session on the same client. This allows to use the regular user session as well as one or more guest sessions in parallel - e.g. if the sharing user quickly wants to check how the contents appear for the guest user after generating a share link.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Whether guest sessions are enabled for auto-login is configurable via the property <code>com.openexchange.share.autoLogin</code> in <code>share.properties</code><br />
* By default, the cookie TTL for guest sessions is inherited from the TTL for cookies of regular sessions as defined by <code>com.openexchange.cookie.ttl</code> - this default may be overridden by defining a timespan at <code>com.openexchange.share.cookieTTL</code><br />
<br />
=== Login Modes ===<br />
<br />
When accessing a share link, one of the following login modes is triggered to acquire a session and forward the client to the share target. The executed login operation and redirect depends on the authentication mode of underlying guest account, the share target iteself, and the client accessing the share.<br />
<br />
==== Redirect to Target ====<br />
<br />
In case a share is accessible without providing credentials, the client is redirected to the share target directly, i.e. without prompting for a username or password. By default, the client is redirected to the target in the App Suite web interface by responding the <code>GET</code> request to the share link with <code>HTTP 302</code>, and a location header like the following:<br />
<br />
<code>Location: /appsuite/ui#!&amp;session=80c711019d6f48b5bec9cd82758e3308&amp;store=true&amp;user=&amp;user_id=642&amp;context_id=1&amp;m=files&amp;f=41042</code><br />
<br />
The session for the guest user is created implicitly in the backend after checking the share link's validity, and the client is instructed to store appropriate cookies in the redirect response, including the &quot;share&quot; cookie:<br />
<br />
<code>Set-Cookie: open-xchange-secret-aNobP2G9wLHJ6sMr7vtTA=38ee770d6e4f42ab8366d91db3279931; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=cae6a3e712ac429e9da9194abd389cb3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ad50ac00418fbcdad50ac1418f94fb181d51b8fa7b2bde3; Expires=Thu, 13-Aug-2015 06:16:26 GMT; Path=/; Secure; HttpOnly</code><br />
<br />
==== Redirect to Login Screen ====<br />
<br />
If additional credentials, i.e. an additional PIN code or username/password combination, are required to access a share target, and no &quot;special client&quot; like an iCal consumer is detected by the backend, the client is redirected to the login screen of the app suite webinterface. The GET request to the share link is answered with statuscode HTTP 302, and a location header depending on the required credentials to access the share.<br />
<br />
If the share ought to be accessed anonymously, but protected by a PIN code, a location like the following is added to the response header:<br />
<br />
<code>Location: /appsuite/ui#!&amp;share=08b4b6110151f1bd7d4b610151f0405d9fc8bb89a887f04e&amp;login_type=anonymous&amp;message_type=INFO&amp;message=Tony%20Parker%20has%20shared%20the%20folder%20%22Pictures%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&amp;target=151ebb38</code><br />
<br />
For shares to dedicated guest users identified by their e-mail address, the redirect location looks like follows:<br />
<br />
<code>Location: /appsuite/ui#!&amp;share=4ac9eb590f9ca4d2ac9eb58f9ca611ec9b4f4638d288c8c0&amp;login_type=guest&amp;message_type=INFO&amp;message=Tony%20Parker%20has%20shared%20the%20file%20%22Agenda.pdf%22%20with%20you.%20Please%20log%20in%20to%20view%20it.%20&amp;login_name=ray%40example.com&amp;target=4444cbc7</code><br />
<br />
The redirect response already contains the <code>Set-Cookie</code> header for the JVM route. On the redirect target, the client should request the PIN code or password from the user, and then issue a special login request, supplying the share token and optional target from the URL parameters, and the password as URL encoded form data in the request body, similar to the usual login request via POST. After successful authentication, the login response includes, along with the common login response properties like the session identifier, information about the share target being accessed:<br />
<br />
<code>{&quot;session&quot;:&quot;b89af2c2ce494ce4b4573c0632b48e89&quot;,&quot;user&quot;:&quot;ray@example.com&quot;,&quot;user_id&quot;:660,&quot;context_id&quot;:1,&quot;locale&quot;:&quot;en_US&quot;,&quot;module&quot;:&quot;files&quot;,&quot;folder&quot;:&quot;10&quot;,&quot;item&quot;:&quot;10/456398&quot;, ... }</code><br />
<br />
Additionally, the client is instructed to store the secret cookies:<br />
<br />
<code>Set-Cookie: open-xchange-share-b7gDSqJpnh9gS3Fs52I65Q=0ac9eb590f9ca4d5ac9eb58f9ca641ec9b4f4638d288c8a0; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-secret-MBIRg9bJBLduCcosqQBCw=70187de16f844be6880c18be373b953d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br /><br />
<code>Set-Cookie: open-xchange-public-session-d0759656127fb7cee6e0fe8bb5fe19f9=4e797a59758a4dd7b763912472ccf26d; Expires=Thu, 13-Aug-2015 06:31:21 GMT; Path=/; Secure; HttpOnly</code><br />
<br />
Afterwards, the client is able to use the session to access the share target as usual.<br />
<br />
=== Session Lifecycle ===<br />
<br />
Generally, guest sessions on the server are treated just like the sessions of ordinary users. Especially, guest sessions are also held in the local session containers of the backend host they're associated with. However, by default guest sessions are marked as <code>transient</code>, i.e. they are not moved to the long-term session containers, nor they are put into the distributed session storage.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* Guest sessions are also accounted in the monitoring outputs (e.g. in the sessions per container graphs)<br />
* The <code>transient</code> handling of guest sessions may be changed via the property <code>com.openexchange.share.transientSessions</code> in <code>share.properties</code><br />
<br />
=== Logout ===<br />
<br />
Guest sessions are terminated once a logout request is issued by the client, i.e. the user clicks the &quot;Logout&quot; button in the web interface, just like it is done for regular sessions. Additionally, guest sessions expire in the backend when not being used for a while, the actual timeout depends on the configured default session lifetime and whether they are treated as &quot;transient&quot; or not, as explained above.<br />
<br />
Since guest users are not able to use the default login page for regular users, a custom logout location for guest users should be specified where guest users are taken to after clicking logout explicitly, or if their session expired.<br />
<br />
If a share is consumed &quot;directly&quot;, e.g. by downloading the binary contents of a file share directly (see [[#Consuming_Shares|Consuming Shares]] for details), the guest sessions is terminated instantly after serving the request.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The logout location for guest accounts can be customized via <code>guestLogoutLocation</code> in the file <code>as-config.yml</code> (see file <code>as-config-default.yml</code> for an example)<br />
<br />
== Share Notifications ==<br />
<br />
With the new sharing concept, notification mails can be sent out to the permission entities (i.e. internal or guest users) of folders or items. Mechanisms exist to send out such mails implicitly or explicitly. Notifications are sent out implicitly, if externals are invited as guests and can also be sent out for internal invitations, if configured so. The client (e.g. App Suite UI) decides on its own whether implicit notifications shall be sent when updating a folders or items permissions. Besides there are separate API calls for sending out notification messages explicitly. Its on the client to provide this functionality to its users. This makes it possible to re-send a link to a folder or item to an existing permission entity.<br />
<br />
Sending out links to shared folders and items is not the only case for notification messages, it can also be necessary to send out system notifications to guest users. Currently this is the case when a guest user secured his account with a password and needs to reset that password, because he cannot remember.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* A special transport must be configured for system notifications and cases where the sharing user has no configured webmail account. This transport is configured in <code>noreply.properties</code>. All properties therein are config-cascade capable, so their values can be sensitive to the current user or context.<br />
* It is possible to disable the implicit notification of internal users about shared folders or items at all by setting <code>com.openexchange.share.notifyInternal</code> in <code>share.properties</code> to <code>false</code>.<br />
* The layout of notifications mails can be changed via <code>as-config.yml</code>. All available properties are defined and explained in <code>as-config-defaults.yml</code>.<br />
<br />
== API Access ==<br />
<br />
From a client's point of view, guest users basically don't differ from regular users, although they usually have limited capabilities, for example no mail access or no personal folders. However, all those differences are reflected within the regular permission- and capability-concepts, so that existing clients, once the guest user is authenticated and has a valid session, continue to work transparently, and use the same API calls as with a regular groupware user.<br />
<br />
To create or manage shares and guest users, the HTTP API has been extended at various locations. The following list gives an overview about the changes, derived from the corresponding software change requests.<br />
<br />
=== Format change for object identifiers of the default &quot;infostore&quot; account ===<br />
<br />
As preparation for individual object permissions where a file can be accessed from different folder &quot;views&quot;, the object IDs for documents in the default &quot;infostore&quot; file storage account will get enhanced with the prefixing folder ID.<br />
<br />
The identifiers will now be of format <code>&lt;some numbers&gt;/&lt;more numbers&gt;</code>. Object identifiers are already of type <code>String</code>, so this change should usually be transparent to clients. However, there may be some clever clients out there that for example tried to interpret the string of numerical characters as number, so client developers should double-check their implementation for compatibility. They most likely would run into trouble when coping with non-infostore file storages anyway.<br />
<br />
=== Object permissions for files ===<br />
<br />
In order to define permissions on object-level, a new property <code>object_permissions</code> for objects of type <code>infoitem</code> is introduced. Each time the underlying folder permissions are not sufficient to access an item, those object permissions are taken into account. Object permissions are stored as an array of Object Permission objects as defined below within the detailed infoitem data, the column ID is <code>108</code>.<br />
<br />
Details about the JSON structure are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionFlags HTTP API: Object Permission Flags]<br />
<br />
=== New field for &quot;user&quot; data: &quot;guest_created_by&quot; ===<br />
<br />
A new property has been introduced for users that needs to be exposed in our HTTP API, too. The following property is added to the detailed user data object:<br />
<br />
* ID: 616<br />
* Name: guest_created_by<br />
* Type: Number<br />
* Value: Contains the ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users<br />
<br />
The property is read-only and can't be removed or set by clients.<br />
<br />
See also:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedUserData HTTP API: Detailed User Data]<br />
<br />
=== Extend folder- and object permissions for addressing external guests ===<br />
<br />
For sharing files- or folders to external guests, the folder- and object permission objects are extended with additional properties. Those extended properties can be set during creation or update of the parent folder or file. The underlying shares and guest user entities for the referenced recipients are created automatically along with folder/file creation/update. Afterwards, the external recipients appear as regular &quot;user&quot; entities in the permission arrays in subsequent &quot;get&quot; requests.<br />
<br />
Details about the extended JSON structure are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#PermissionObject HTTP API: Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ObjectPermissionObject HTTP API: Object Permission Object]<br />
<br />
=== New Ajax module: share/management ===<br />
<br />
To work with shares, a new Ajax module is introduced.<br />
<br />
The available actions in the module are described at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Module_.22share.2Fmanagement.22_.28preliminary.2C_available_with_v7.8.0.29 HTTP API: Module share management]<br />
<br />
=== New column &quot;shareable&quot; in detailed infoitem data ===<br />
<br />
Clients want to know quickly if an infostore item is shareable or not. A new (read-only) property named <code>shareable</code> of type Boolean with column identifier <code>109</code> is introduced for &quot;detailed infoitem data&quot;. If &quot;true&quot;, the can be considered as shareable, i.e. the item's object permissions may be adjusted by the user.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#DetailedInfoitemData HTTP API: Detailed Infoitem Data]<br />
<br />
=== New action &quot;shares&quot; in module folder ===<br />
<br />
To provide an overview of all folders of a certain modules that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>folders</code>. It returns all personal folders of a certain module that are shared to other entities.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared folders]<br />
<br />
=== New action &quot;shares&quot; in module infostore ===<br />
<br />
To provide an overview of all files that are shared to others, a new <code>shares</code> action is added to the Ajax module <code>infostore</code>. It returns all personal files that are shared to other entities.<br />
<br />
Further details are available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29 HTTP API: Get shared infoitems]<br />
<br />
=== New fields to retrieve extended permissions of files and folders ===<br />
<br />
Clients would like to have more details about permission entities folders directly. A new read-only property named <code>com.openexchange.share.extendedPermissions</code> is introduced for &quot;Detailed folder data&quot;, with column identifier <code>3060</code>. It basically contains the same as the regular <code>permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.<br />
<br />
Similarly, a new read-only property named <code>com.openexchange.share.extendedObjectPermissions</code> is introduced for &quot;Detailed infoitem data&quot;, with column identifier <code>7010</code>. It basically contains the same as the regular <code>object_permissions</code> array, yet enhanced by resolved information about the user, group or guest entities as well as additional, sharing-related properties.<br />
<br />
Further information about the JSON structure is available at:<br />
<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedPermissionObject HTTP API: Extended Permission Object]<br />
* [http://oxpedia.org/index.php?title=HTTP_API#ExtendedObjectPermissionObject HTTP API: Extended Object Permission Object]<br />
<br />
== Consuming Shares ==<br />
<br />
Depending on the shared contents and the requesting user agent, shares may be consumed in a couple of different ways. The concrete response to a request to the share URL is evaluated by the share servlet in the backend.<br />
<br />
=== App Suite ===<br />
<br />
The default handling for all shares is forwarding them to the App Suite web interface, where the shared contents are made available through the existing client. Based on the underlying guest account, the client is either forwarded to the login prompt, or taken directly to the share target if no credentials need to be provided. This process is described in more detail at [[#Guest_Login_&_Session_Handling|Guest Login &amp; Session Handling]].<br />
<br />
=== Direct Download ===<br />
<br />
Shares to a single file may also be downloaded directly by clients, without opening them in the web interface first. This is indicated by an additional parameter appended to the plain share link, and can be specified in the following ways:<br />
<br />
* Append <code>dl</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?dl=true</code><br />
* Specify <code>delivery</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?delivery=download</code><br />
<br />
If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an &quot;anonymous&quot; share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like &quot;Guest&quot;.<br />
<br />
=== Get iCal ===<br />
<br />
Shares to a single calendar- or task-folder may also be downloaded directly by clients as iCal files, without opening them in the web interface first. This standard format allows to consume event data directly using various calendaring clients, which often can be configured to subscribe an external calendar source.<br />
<br />
Once a share link to a calendar- or task-folder is requested by the client, the <code>Accept</code>- and <code>User-Agent</code> headers of the request are evaluated. If the <code>Accept</code> header is either set to <code>text/calendar</code> or <code>text/iCal</code>, or if the <code>User-Agent</code> header denotes a well-known client like Microsoft Outlook or Mozilla Thunderbird w/ Lightning, the contents of the shared folder are converted to an iCal file that is directly written back in the response.<br />
<br />
To force the iCal output, an additional parameter may be appended to the plain share link:<br />
<br />
* Append <code>ical</code> parameter:<br /><br />
<code>https://ox.example.com/ajax/share/48b2b6190151f1bd8b4b610151f0405d9fc8cb89a087f14e/151eab38?ical=true</code><br />
<br />
If accessing the item requires authentication, an unauthenticated request is responded with <code>HTTP 401 Unauthorized</code>. The client then has to provide the correct credentials to access the share via basic authentication. If there's no dedicated username for the underlying guest account - i.e. an &quot;anonymous&quot; share link protected with a PIN code is accessed - only the password is checked, i.e. the client may then supply an arbitrary username in the basic authentication header like &quot;Guest&quot;.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The interval of task- and appointment data considered for conversion to iCal can be adjusted via <code>com.openexchange.share.handler.iCal.futureInterval</code> and <code>com.openexchange.share.handler.iCal.pastInterval</code> in configuration file <code>share.properties</code><br />
<br />
== Cross-context functionality ==<br />
<br />
As already mentioned in previous sections the administrator is able to configure if guests should be handled per context (default) or server wide by using the configuration parameter <code>com.openexchange.share.crossContextGuests</code>.<br />
<br />
If set to <code>true</code> the guests email address is used to recognize if there is already a registered user with the given address and aligns the stored password to the already existing guest user. In addition to the password (which is the most important parameter this feature is about) even the users contact data gets synchronized.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* To handle user and contact data across contexts boundaries the feature has to be enabled before a guest receives the first share. Guests that receive shares before the activation cannot be considered within the alignment process. Only latter shares will be considered.<br />
* At the moment this feature does only sync user and contact related data (no shared content). If the user got two shares from different contexts he will only see shares related to the given link.<br />
<br />
== Publish/Subscribe vs. Sharing ==<br />
<br />
The upcoming sharing features are going to replace the previously used OXMF &quot;publications&quot;, allowing guest users to interact with the shared data in the same way as regular groupware users do. However, since the underlying concepts and their technical realization are completely different, a seamless migration between publications and shares is not possible without some drawbacks.<br />
<br />
The following list gives an overview of the main discrepancies:<br />
<br />
* Custom templates for OXMF publication targets<br />An adminsitrator/admin may have defined some custom publication targets that are using the published data in a special way. While shares would still make all the data available (mainly via the web interface), this would only be a drop-in replacement for the ordinary &quot;view the publication in a browser&quot; use case, but not for anything beyond that scope.<br />
* Subscribe of publications<br />Publications from one user can be added to another user's groupware using the &quot;subscribe&quot; functionality, making use of the embedded microformat data of publications (OXMF). For sharing, we will not have a similar feature in the first iteration, so migrating an existing publication to a share would also stop it from being subscribable.<br />
* Deep links to download files of publications<br />Files behind an infostore publication were accessible behind a static URL, which would theoretically allow them to be requested independently of the parent publication (e.g. images linked from an external website). While the entry URL to a publication would be mappable to a corresponding share URL, converting existing publications to shares would at least break such deep links.<br />
<br />
Because of the above points and the whole different concept, we do not migrate existing publications to shares. Instead, the default behavior will be:<br />
<br />
* No new OXMF publications or subscriptions can be created by default<br />
* The web client does no longer give the option to publish or subscribe in the OXMF format<br />
* Existing OXMF publications / subscriptions can't be updated<br />
* Existing OXMF publications continue to work as is, including associated subscriptions<br />
* Yet it's still possible to delete existing publications and subscriptions<br />
* Therefore, the menu section &quot;Publications and Subscriptions&quot; will still be available (if there's at least one publication or subscription)<br />
<br />
Exceptions to these rules cover special internal subscriptions to 3rd party services like addressbooks from LinkedIn or Xing, as well as the auto-publish feature of mail attachments exceeding a specific size.<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The possibility to create/update OXMF publications via HTTP-API may be configured via <code>com.openexchange.publish.createModifyEnabled</code> in file <code>publications.properties</code><br />
* The possibility to create/update OXMF subscriptions via HTTP-API may be configured via <code>com.openexchange.subscribe.microformats.createModifyEnabled</code> in file <code>microformatSubscription.properties</code><br />
<br />
<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21485AppSuite:OX Drive2016-02-15T09:56:19Z<p>Steffen.templin: /* 7.8.1 and later */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
To make the client download available via the client onboarding wizard, you need to enable the according scenario. Edit ''/opt/open-xchange/etc/client-onboarding-scenarios.yml'' and get to the ''drivewindowsclientinstall'' section, where you have to set the ''enabled'' property to ''true''.<br />
<br />
<br />
Please note that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21484AppSuite:OX Drive2016-02-12T15:42:16Z<p>Steffen.templin: /* SUSE Linux Enterprise Server 12 */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21483AppSuite:OX Drive2016-02-12T15:40:41Z<p>Steffen.templin: /* SUSE Linux Enterprise Server 11 */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21482AppSuite:OX Drive2016-02-12T15:39:38Z<p>Steffen.templin: /* Debian GNU/Linux 8.0 */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21481AppSuite:OX Drive2016-02-12T15:38:16Z<p>Steffen.templin: /* Debian GNU/Linux 7.0 */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21480AppSuite:OX Drive2016-02-12T15:37:24Z<p>Steffen.templin: /* Debian GNU/Linux 7.0 */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21479AppSuite:OX Drive2016-02-12T15:36:31Z<p>Steffen.templin: /* Redhat Enterprise Linux 7 or CentOS 7 */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21478AppSuite:OX Drive2016-02-12T15:35:53Z<p>Steffen.templin: /* Redhat Enterprise Linux 6 or CentOS 6 */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-client-generic}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21467AppSuite:OX Drive2016-02-11T11:01:28Z<p>Steffen.templin: /* Installation of Windows Desktop Client */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
See [[AppSuite:OX_Drive#OX_Drive_for_Windows|OX Drive for Windows]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Drive&diff=21466AppSuite:OX Drive2016-02-11T10:57:49Z<p>Steffen.templin: /* Server-side Installation and Configuration */</p>
<hr />
<div>= OX Drive =<br />
<br />
In OX App Suite, Open-Xchange provides a cloud storage called OX Drive. It provides file- and folder synchronization across multiple devices in the most simplest way for the end user, fully optimized for each device type. This article explains how to set up the server-side components for OX Drive, as well as details about the client setup.<br />
<br />
== Key features ==<br />
<br />
* Native Apps for Windows, Mac OS, iOS and Android<br />
* Easy and attractive upsell properties (e.g. Upsell based on Quota limitations)<br />
* Clients are specially designed for the devices they run on taking into account limitations such as battery life, screen limitations, bandwidth etc.<br />
* Controlled synchronization of files across devices<br />
* Storage management (e.g. quota control, upload limits)<br />
* Connection type recognition and adaptation (e.g. Wi-Fi, cell network)<br />
<br />
== Availability ==<br />
<br />
OX Drive is a combination of two components:<br />
* OX Drive in OX App Suite<br />
* OX Drive Clients (optional native client components for synchronization)<br />
<br />
OX Drive is available for the following native clients:<br />
* OX Drive for Windows<br />
* OX Drive for Mac OS<br />
* OX Drive for iOS<br />
* OX Drive for Android<br />
<br />
== Requirements ==<br />
<br />
You will find the requirements under [[AppSuite:OX_System_Requirements#OX_Drive_for_Clients|OX Drive Client and Platform Requirements]]<br />
<br />
= Server-side Installation and Configuration =<br />
<br />
This chapter describes how the backend components of OX Drive are installed and configured on the server.<br />
<br />
== Prerequisites ==<br />
<br />
* Open-Xchange Server v7.4.2 and above (''open-xchange-core'')<br />
* Grizzly HTTP connector (''open-xchange-grizzly''), see [[AppSuite:Grizzly]] for details, with ''Comet'' support enabled in ''grizzly.properties''<br />
* Valid Push-Certificates / API keys for cloud-based notifications, see configuration below<br />
* Enabled Hazelcast for inter-OX-communication, see [[AppSuite:Running_a_cluster]] for details<br />
<br />
== Available packages ==<br />
<br />
Open-Xchange Drive is available with the following backend packages:<br />
<br />
* ''open-xchange-drive'' - The main server components for OX Drive<br />
* ''open-xchange-drive-comet'' - Provides the Push interface via long-polling for the desktop clients<br />
* ''open-xchange-drive-help-*'' - Online help in various languages for the OX Drive applications (these were called ''open-xchange-appsuite-help-drive-*'' in versions earlier than Open-Xchange Server v7.6.2)<br />
* ''open-xchange-drive-restricted'' - Restricted components, including prerequisites for cloud-based push notifications<br />
<br />
Installation on the server varies depending on the underlying distribution, details are available in the following chapters.<br />
<br />
=== OX Drive for Windows ===<br />
<br />
Additionally OX Drive for Windows can be provided to users by installing additional packages. However there are significant differences between 7.80 and earlier releases and 7.8.1 and later ones:<br />
<br />
==== 7.8.0 and earlier ====<br />
<br />
OX Drive for Windows can be provided via the [[AppSuite:Open-Xchange_Updater|Open-Xchange Updater]] by installing the package ''open-xchange-updater-drive''. Initial installation and updates are performed by the Updater then.<br />
<br />
==== 7.8.1 and later ====<br />
<br />
With OX App Suite 7.8.1 and OX Drive for Windows 2.0.0, the client is able to update itself and can be downloaded from the Web UI directly via the [[AppSuite:Client_Onoarding|Client Onboarding Wizard]]. Therefore the wizard must be installed and configured for OX Drive users. Besides the client onboarding feature you need the following packages:<br />
<br />
* ''open-xchange-drive-client-windows'' - The main server component to provide the client<br />
* ''open-xchange-drive-client-windows-generic'' - The package providing the final binary files to be installed on users machines.<br />
<br />
Besides that there still exists a compatibility layer between the old Updater-based approach and the new direct install and self-update one. If you start providing OX Drive for Windows with 7.8.1 or later you MAY decide to enable that compatibility by installing ''open-xchange-updater-drive'', however we advice not to do so. If you already provided OX Drive for Windows with 7.8.0 or earlier, you MUST install this package and further provide the Updater. Otherwise the clients out there will not be able to be updated to the 2.0.0 version, which is then self-update capable.<br />
<br />
===== Custom branded clients =====<br />
<br />
OX Drive for Windows can be purchased with a custom theming. In such cases, the according binary files need to be installed on the middleware servers. Instead of the ''open-xchange-drive-client-windows-generic'' package, a package containing the branded binaries will be provided as ''open-xchange-drive-client-windows-<brand-name>'' and needs to be installed. You MUST then set the property ''com.openexchange.drive.update.branding'' in ''/opt/open-xchange/etc/drive-client-windows.properties'' to ''<brand-name>'' accordingly.<br />
<br />
It is also possible to provide multiple brands of the client via the same OX App Suite deployment, multiple ''open-xchange-drive-client-windows-<brand-name>'' packages can be installed in parallel. Which brand is available for a certain user is determined by the ''com.openexchange.drive.update.branding'' property, which can be overwritten via [[ConfigCascade|Config Cascade]] therefore.<br />
<br />
Client brands can be managed via command line tools. The tool ''/opt/open-xchange/sbin/listdriveclients'' lists all installed brands. After updating a certain brand by installing a newer package version or installing an additional one, no server restart is necessary. Instead ''/opt/open-xchange/sbin/reloaddriveclients'' can be executed to refresh the internal server state.<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/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL6|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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 />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|backend}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|drive-help}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=YUMRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=rhelname|pc2v=RHEL7|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ yum update<br />
$ yum install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianWheezy|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== Debian GNU/Linux 8.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/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|backend}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|drive-help}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=APTRepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=debianname|pc2v=DebianJessie|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
and run<br />
<br />
$ apt-get update<br />
$ apt-get install open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<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/appsuite/stable|pc2n=susename|pc2v=SLES11|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLES11|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== SUSE Linux Enterprise Server 12 ===<br />
<br />
Add the package repository using zypper if not already present:<br />
<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|backend}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|drive-help}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/appsuite/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|backend/updates|drive|updater}}<br />
{{for loop||call=SUSERepo|pv=reponame|pc1n=path|pc1v=products/drive/stable|pc2n=susename|pc2v=SLE_12|pc3n=ldbaccount|pc3v=LDBUSER:LDBPASSWORD|drive-help/updates}}<br />
<br />
and run<br />
<br />
$ zypper ref<br />
$ zypper in open-xchange-drive open-xchange-drive-comet open-xchange-drive-restricted open-xchange-drive-client-windows<br />
<br />
=== OX Server Edition / App Suite for UCS ===<br />
<br />
If you have purchased the OX Server Edition / App Suite for UCS, the OX Drive is part of the offering and after the installation/update available. The necessary package for push, is available with a valid license and can be installed via the Univention App Center.<br />
<br />
* The new license is already registered at the LDB after purchase.<br />
* Log on at the Univention Management Console (UMC)<br />
* Make sure, that the correct LDB account has been selected in the UMC module "OX License Management"<br />
* Click on "App Center" at the UMC und switch to the tab "Repository Settings"<br />
* Within the component list, select "Open-Xchange Drive" and press the "Install" button<br />
<br />
== Configuration ==<br />
<br />
The following gives an overview about the most important settings to enable file synchronization via OX Drive, especially when it comes to real-time Push notifications for the client applications.<br />
<br />
All settings regarding the OX Drive backend component are located in the configuration file ''drive.properties''. The default configuration should be sufficient for a basic "up-and-running" setup (with the exception of defining the Push certificates and API keys for cloud-based client notifications, see next chapters). Please refer to the inline documentation of the configuration file for more advanced options. <br />
<br />
=== Push via Google Cloud Messaging (GCM) ===<br />
<br />
The OX Drive application for Android devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.android.com/google/gcm/index.html Google Cloud Messaging (GCM)]. To issue those Push messages, the backend needs to be provided with a suitable API key for the corresponding Android client application. The API key is included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" Android client application. Alternatively, the key can be specified directly in the ''drive.properties'' configuration file:<br />
<br />
# Specifies the API key of the server application. Required if <br />
# "com.openexchange.drive.events.gcm.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.gcm.key=<br />
<br />
Push via GCM can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Google<br />
# Cloud Messaging (GCM) service. This requires a valid configuration for the <br />
# GCM API key, see options below. Defaults to "false". <br />
com.openexchange.drive.events.gcm.enabled=true<br />
<br />
Please note that push via GCM needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Push via Apple Push Notification service (APNs) ===<br />
<br />
The OX Drive application for iOS and Mac OS devices is able to receive Push notifications from the Open-Xchange Server via [http://developer.apple.com/library/IOS/documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html Apple Push Notification service (APNs)]. To issue those Push messages, the backend needs to be provided with a suitable keystore container file (PKCS #12) containing the APNs certificate and keys. Note that the Mac OS desktop client and the iOS mobile client are served separately with different certificates, so that both needs to be configured independantly. The required certificates are already included in the restricted components installation package ''open-xchange-drive-restricted'' for the "vanilla" iOS and Mac OS client applications. Alternatively, the certificate can be specified directly in the ''drive.properties'' configuration file (the following only shows the setup for iOS). First, the path to the PKCS #12 container file needs to be specified at:<br />
<br />
# Specifies the path to the local keystore file (PKCS #12) containing the APNS <br />
# certificate and keys for the iOS application, e.g. <br />
# "/opt/open-xchange/etc/drive-apns.p12". Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.keystore=<br />
<br />
This file is opened by the backend using the password as supplied via: <br />
<br />
# Specifies the password used when creating the referenced keystore containing<br />
# the certificate of the iOS application. Note that blank or null passwords <br />
# are in violation of the PKCS #12 specifications. Required if <br />
# "com.openexchange.drive.events.apn.enabled" is "true" and the package <br />
# containing the restricted drive components is not installed.<br />
com.openexchange.drive.events.apn.ios.password=<br />
<br />
Configuration also allows to swith between development and production environments, however, this setting should be ''true'' normally:<br />
<br />
# Indicates which APNS service is used when sending push notifications to iOS<br />
# devices. A value of "true" will use the production service, a value of <br />
# "false" the sandbox service. Defaults to "true".<br />
com.openexchange.drive.events.apn.ios.production=true<br />
<br />
The OX backend contacts the APNs servers from time to time to get informed about clients no longer reachable clients where the applications was uninstalled. The interval can be defined with the following setting: <br />
<br />
# Configures the interval between queries to the APN feedback service for the<br />
# subscribed iOS devices. The value can be defined using units of measurement: <br />
# "D" (=days), "W" (=weeks) and "H" (=hours). Defaults to "1D" (one day). <br />
# Leaving this parameter empty disables the feedback queries on this node. <br />
# Since each received feedback is processed cluster-wide, only one node in the <br />
# cluster should be enabled here. <br />
com.openexchange.drive.events.apn.ios.feedbackQueryInterval=1D<br />
<br />
Please note that if you have multiple backend nodes in the cluster, it's recommended that only one node is configured to contact the feedback query service. Finally, Push notifications via APN for iOS can be enabled via:<br />
<br />
# Enables or disables push event notifications to clients using the Apple Push<br />
# Notification service (APNS) for Mac OS devices. This requires a valid <br />
# configuration for the APNS certificate and keys, see either options below, <br />
# or install the restricted components packages for drive. Defaults to <br />
# "false". <br />
com.openexchange.drive.events.apn.ios.enabled=false<br />
<br />
As stated above, configuration for Push notifications via APN for the Mac OS desktop application is configured similarly, the relevant options are prefixed with ''com.openexchange.drive.events.apn.macos''. Please also note that push via APNS needs to be enabled explicitly - also if ''open-xchange-drive-restricted'' is installed.<br />
<br />
=== Further Configuration ===<br />
<br />
* The backend component of OX Drive supplies the clients with various hyperlinks, e.g. deep-links to files and folders in the groupware webinterface or an URL to the online help. In order to point to the suitable web interface, please ensure that the correct UI web path is configured via ''com.openexchange.UIWebPath'' located in ''server.properties''.<br />
* As already mentioned above, the backend relies on the [https://grizzly.java.net/comet.html Comet] component of the Grizzly http connector for sending push notifications to the desktop clients. Therefore, ''com.openexchange.http.grizzly.hasCometEnabled'' needs to be set to ''true'' in ''grizzly.properties''.<br />
<br />
= Enabling OX Drive for Users =<br />
<br />
OX Drive is enabled for all users that have the capability ''com.openexchange.capability.drive''. Please note that users need to have the ''infostore'' permission set to use drive. So the users that have ''drive'' enabled must be a subset of those users with ''infostore'' permission. Since 7.6.0 we enforce this via the default configuration. You can also enable this cabaility globally with the following setting in the ''drive.properties'' configuration file:<br />
<br />
# Enables or disables the "drive" module capability globally. The capability<br />
# can also be set more fine-grained via config cascade. Per default it is only<br />
# enabled for users that have the "infostore" permission set. This is configured<br />
# in /opt/open-xchange/etc/contextSets/drive.yml.<br />
com.openexchange.capability.drive=false<br />
<br />
More details about capabilities can be found at [[AppSuite:Capabilities]]. Furthermore, this capability can be defined in a more granular way using the Config Cascade as described at [[ConfigCascade]].<br />
<br />
= Installation of the Clients =<br />
<br />
== Installation of Mac OS X Desktop Client ==<br />
<br />
The OX Drive for Mac OS X will be provided via the Apple App Store:<br />
<br />
* https://itunes.apple.com/app/ox-drive/id818195014?mt=12<br />
<br />
== Installation of Windows Desktop Client ==<br />
<br />
The OX Drive for Windows will be provided direct at the OX App Suite via the [[AppSuite:Open-Xchange_Updater|OX Updater]].<br />
<br />
== Installation on Mobile Clients ==<br />
<br />
The OX Drive App is available via the different App Stores:<br />
<br />
* iOS: https://itunes.apple.com/app/ox-drive/id798570177?mt=8<br />
<br />
* Android: https://play.google.com/store/apps/details?id=com.openexchange.drive.vanilla<br />
<br />
<br />
== Client Configuration and Deployment ==<br />
<br />
The user needs to enter the server URL and provide his username and password. Afterwards, client-specific settings may be configured. This includes the synchronization mode (All files / Favorites only) and Photostream settings on mobile devices, or the local root synchronization folder for the desktop applications. More information is available in the online documentation. <br />
<br />
After the initial synchronization is completed, all further changes are synchronized instantly across all devices.<br />
<br />
<br />
= FAQ =<br />
<br />
'''How to limit the maximum file size, a configured ''MAX_UPLOAD_SIZE'' seems to have no effect for uploads from OX Drive clients?'''<br />
<br />
This setting has no effect for files uploaded from OX Drive clients, since big uploads may also be processed via multiple requests in smaller chunks. We plan to offer a separate configuration option in a future release.<br />
<br />
'''There are strange files and folders on the backend, where do they come from, is it safe to delete them?'''<br />
<br />
To support chunked uploads, and to optimize the synchronization process, the synchronization logic may create various temporary files (''.drive'' directory and contained files). They only appear in the web interface if the setting ''Show hidden files and folders'' is enabled, and are removed automatically if not accessed for a specific period (default: 1 day).<br />
<br />
'''Not all files and folders get synchronized. Are there any restrictions?'''<br />
<br />
Yes, please consult the online help for a detailed list of excluded files and folders.<br />
<br />
'''How do I synchronize a shared or public folder?'''<br />
<br />
Currently, only the synchronization of a single root folder (and all of it's subfolders) is possible. For the mobile client applications, this is always the default personal drive folder of the user, while the desktop clients allow to choose which folder to synchronize. The synchronization of multiple root folders is scheduled for a future release.</div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=AppSuite:OAuth_2_0_Provider_Operator_Guide&diff=21381AppSuite:OAuth 2 0 Provider Operator Guide2016-02-06T12:45:48Z<p>Steffen.templin: </p>
<hr />
<div>{{Version|7.8.0}}<br />
<br />
= Open-Xchange OAuth 2.0 Provider Operator Guide =<br />
<br />
With OX App Suite v7.8.0 a service provider can decide to publish a certain subset of the OX HTTP API via OAuth 2.0. See the [[AppSuite:OAuth_2_0_Client_Developer_Guide|developer guide]] for an overview of the available APIs. The feature as a whole is contained in separate optional packages and requires some configuration. Supported client applications must be of type <code>confidential</code> according to the <code>web application</code> profile defined in [http://tools.ietf.org/html/rfc6749 RFC 6749]. The OX middleware will act as <code>resource server</code> and by default also as <code>authorization server</code>.<br />
<br />
When acting as <code>authorization server</code>, every application must be registered at the OX backend. The registration process is up to you, while the backend provides SOAP and RMI interfaces to persist those registrations and generates the client-specific credentials that are needed to gain access for granting users. With OX App Suite v7.8.1 it is possible to use an external authorization server.<br />
<br />
== Installation and Configuration ==<br />
<br />
The OAuth provider feature is separated into two packages <code>open-xchange-oauth-provider</code> and <code>open-xchange-admin-oauth-provider</code>. The former one needs to be installed on every groupware node, the latter one provides the client provisioning interfaces and may be installed on your dedicated provisioning nodes. On a Debian setup you would install those packages like so:<br />
<br />
<pre>$ apt-get install open-xchange-oauth-provider open-xchange-admin-oauth-provider</pre><br />
<br />
Configuration takes place in <code>/opt/open-xchange/etc/oauth-provider.properties</code>. The feature is disabled by default and must be activated manually.<br />
<br />
== Using the internal authorization server ==<br />
<br />
'''Note:''' Using an external authorization server is earliest possible with v7.8.1.<br />
<br />
The internal authorization server needs some configuration, that also takes place in <code>/opt/open-xchange/etc/oauth-provider.properties</code>. An encryption key is used to encrypt the credentials of client applications within the database. You MUST set a value here and this value must be the same on all groupware and provisioning nodes. Example:<br />
<br />
<pre># Set to 'true' to basically enable the OAuth 2.0 provider. This setting can then be overridden<br />
# via config cascade to disallow granting access for certain users. If the provider is enabled,<br />
# an encryption key (see below) must be set!<br />
#<br />
# Default: false<br />
com.openexchange.oauth.provider.enabled=true<br />
<br />
# Defines whether the enabled OAuth 2.0 provider does not only act as resource server but also<br />
# as authorization server. If 'true' the following functionality will be provided:<br />
# * An authorization endpoint, token endpoint and revocation endpoint are made available via HTTP<br />
# * API calls for revoking access to external clients are made available, access can be revoked via<br />
# App Suite UI<br />
# * Provisioning interfaces to manage trusted clients are enabled<br />
#<br />
# If set to 'false' while the provider itself is enabled, a custom bridge to the external authorization<br />
# server must be provided.<br />
#<br />
# Default: true<br />
com.openexchange.oauth.provider.isAuthorizationServer=true<br />
<br />
# Specify how authorization codes shall be stored, to enable OAuth in multi-node environments.<br />
# Options are Hazelcast ('hz') or database ('db').<br />
#<br />
# Default: hz<br />
com.openexchange.oauth.provider.authcode.type=hz<br />
<br />
# The key to encrypt client secrets that are stored within the database.<br />
# A value must be set to enable the registration of OAuth 2.0 client<br />
# applications. It must be the same on every node. After the first client<br />
# has been registered, the key must not be changed anymore.<br />
# Default: &lt;empty&gt;<br />
com.openexchange.oauth.provider.encryptionKey=yen8oT0vohNgoo9mohfai3aitho6eaQu7cieFohsoamooS3IeJeukoov4niechoh</pre><br />
You may to decide how authorization codes are stored. Those codes are short-living one-time tokens that are generated when a user grants access. The client application will then exchange this code for a pair of access and refresh tokens. We store those codes in the hazelcast data grid per default. However you can choose to store them within the database. If using hazelcast, you can also adjust the parameters for the according distributed data structure in <code>/opt/open-xchange/etc/hazelcast/authcode.properties</code>.<br />
<br />
== Client Provisioning ==<br />
<br />
For every client application that you want to allow to access the OAuth APIs you need to persist some data. During the registration call a client ID and a secret are generated, which must be provided to the client developers.<br />
<br />
'''Important:''' A client does always belong to a context group and is stored within the global DB. It can therefore only handle users of the according contexts. As a result you need to pass a context group name to some of the provisioning calls unless a client ID is required. After registering a client, the context group identifier is encoded within the client ID.<br />
<br />
The registration data consists of the following parameters:<br />
<br />
<table><br />
<br />
<tr><br />
<th>Parameter</th><br />
<th>Description</th><br />
<th>Required</th><br />
</tr><br />
<br />
<br />
<tr><br />
<td>name</td><br />
<td>The name of the client application. Will be visible to your users.</td><br />
<td>Yes</td><br />
</tr><br />
<tr><br />
<td>description</td><br />
<td>A description of the client application. Will be visible to your users. Translations of the description are currently not supported, you must decide for one language.</td><br />
<td>Yes</td><br />
</tr><br />
<tr><br />
<td>contact address</td><br />
<td>E-Mail address to contact the application vendor.</td><br />
<td>Yes</td><br />
</tr><br />
<tr><br />
<td>website</td><br />
<td>An URL to the client applications website.</td><br />
<td>Yes</td><br />
</tr><br />
<tr><br />
<td>default scope</td><br />
<td>A default scope that will be applied if the client application asks a user for access without providing a certain scope during the request. See the developer guide for available scope tokens. The scope is always a space-delimited string cosisting of one or more scope tokens, e.g. "read_contacts write_contacts".</td><br />
<td>Yes</td><br />
</tr><br />
<tr><br />
<td>icon</td><br />
<td>An icon of the client application. Supported image types are <code>image/png</code>, <code>image/jpg</code> and <code>image/jpeg</code>. Icons SHOULD be of size 128x128 px, otherwise they might not get displayed correctly. The max. image size is 256kb.</td><br />
<td>Yes</td><br />
</tr><br />
<tr><br />
<td>redirect URIs</td><br />
<td>One or more URIs that will be used as redirect locations to deliver authorization codes or error messages back to the client application. Every URI must be absolute and not contain a fragment. The scheme must always be <code>https</code>, however for development purposes redirect URIs pointing to <code>localhost</code>, <code>127.0.0.1</code> or <code>[::1]</code> are also allowed with <code>http</code> as scheme.</td><br />
<td>Yes</td><br />
</tr><br />
<br />
</table><br />
== RMI Provisioning ==<br />
<br />
To use RMI as provisioning mechanism you need to link your code against the correct API classes. You'll find the according JAR files on your provisioning node. Navigate to <code>/opt/open-xchange/libs</code> and fetch <code>com.openexchange.admin.rmi.jar</code> and <code>com.openexchange.oauth.provider.rmi.jar</code>. Note that both files are symlinks. Besides the JARs you'll find the according JavaDoc in <code>/usr/share/doc/open-xchange-admin/javadoc</code> and <code>/usr/share/doc/open-xchange-oauth-provider/javadoc</code>. After adding both JARs to your classpath you can start development. The remote interface is <code>com.openexchange.oauth.provider.rmi.RemoteClientManagement</code>. Below you find an example of all operations that manipulate client data. Of course there are also methods to list and get all or certain registered clients.<br />
<br />
<pre>package me.coolhosting.ox.oauth;<br />
<br />
import java.io.ByteArrayOutputStream;<br />
import java.io.FileInputStream;<br />
import java.io.FileNotFoundException;<br />
import java.io.IOException;<br />
import java.net.MalformedURLException;<br />
import java.rmi.Naming;<br />
import java.rmi.NotBoundException;<br />
import java.rmi.RemoteException;<br />
import java.util.ArrayList;<br />
import java.util.List;<br />
import com.openexchange.admin.rmi.dataobjects.Credentials;<br />
import com.openexchange.admin.rmi.exceptions.InvalidCredentialsException;<br />
import com.openexchange.oauth.provider.rmi.client.ClientDto;<br />
import com.openexchange.oauth.provider.rmi.client.ClientDataDto;<br />
import com.openexchange.oauth.provider.rmi.client.RemoteClientManagementException;<br />
import com.openexchange.oauth.provider.rmi.client.IconDto;<br />
import com.openexchange.oauth.provider.rmi.client.RemoteClientManagement;<br />
<br />
public class ClientProvisioningRoundtrip {<br />
<br />
public static void main(String[] args) {<br />
try {<br />
// Lookup remote<br />
RemoteClientManagement clientManagement = <br />
(RemoteClientManagement) Naming.lookup(<br />
&quot;rmi://coolhosting.me:1099/&quot; + RemoteClientManagement.RMI_NAME);<br />
<br />
// All method calls require the master credentials.<br />
Credentials credentials = new Credentials(&quot;oxadminmaster&quot;, &quot;secret&quot;);<br />
<br />
ClientDataDto clientData = prepareClientData();<br />
ClientDto client = clientManagement.registerClient(<br />
RemoteClientManagement.DEFAULT_GID, // use default context group<br />
clientData,<br />
credentials);<br />
<br />
System.out.println(&quot;Client '&quot; + client.getName() + &quot;' was successfully &quot; +<br />
&quot;registered: [ID: &quot; + client.getId() + &quot;, secret: &quot; + client.getSecret() + &quot;]&quot;);<br />
<br />
// You can disable clients temporarily. API access is then prohibited.<br />
if (clientManagement.disableClient(client.getId(), credentials)) {<br />
System.out.println(&quot;Client '&quot; + client.getName() + &quot;' was disabled&quot;);<br />
}<br />
<br />
// Of course enabling disabled clients is also possible.<br />
if (clientManagement.enableClient(client.getId(), credentials)) {<br />
System.out.println(&quot;Client '&quot; + client.getName() + &quot;' was enabled again&quot;);<br />
}<br />
<br />
// You can revoke a clients secret. For security reasons all existing grants<br />
// are invalidated then.<br />
client = clientManagement.revokeClientSecret(client.getId(), credentials);<br />
System.out.println(&quot;Client '&quot; + client.getName() + &quot;' was assigned a new &quot; +<br />
&quot;secret: &quot; + client.getSecret());<br />
<br />
// Of course you can update the client data. Every field set within ClientData<br />
// will be overridden. Fields that are not set will not be modified. Scope and<br />
// redirect URIs must always be submitted in total, no merging will be applied<br />
// here.<br />
clientData = new ClientDataDto();<br />
clientData.setDescription(&quot;A new and fancy client description.&quot;);<br />
client = clientManagement.updateClient(client.getId(), clientData, credentials);<br />
System.out.println(&quot;Client '&quot; + client.getName() + <br />
&quot;' got a new description: &quot; + client.getDescription());<br />
<br />
// You can unregister clients completely and withdraw their granted accesses.<br />
if (clientManagement.unregisterClient(client.getId(), credentials)) {<br />
System.out.println(&quot;Client '&quot; + client.getName() + <br />
&quot;' was successfully unregistered&quot;);<br />
}<br />
} catch (MalformedURLException | RemoteException | NotBoundException | <br />
RemoteClientManagementException | InvalidCredentialsException |<br />
FileNotFoundException e) {<br />
<br />
e.printStackTrace();<br />
}<br />
}<br />
<br />
private static ClientDataDto prepareClientData() throws FileNotFoundException {<br />
IconDto icon = new IconDto();<br />
icon.setData(loadIcon()); // the icon serialized as an array of bytes<br />
icon.setMimeType(&quot;image/png&quot;);<br />
<br />
List&lt;String&gt; redirectURIs = new ArrayList&lt;&gt;(2);<br />
redirectURIs.add(&quot;http://localhost/oauth/callback&quot;); // URI for local testing<br />
redirectURIs.add(&quot;https://example.com/api/oauth/callback&quot;); // production URI<br />
<br />
ClientDataDto clientData = new ClientDataDto();<br />
clientData.setName(&quot;Example.com&quot;);<br />
clientData.setDescription(&quot;The Example.com web apps description.&quot;);<br />
clientData.setIcon(icon);<br />
clientData.setContactAddress(&quot;support@example.com&quot;);<br />
clientData.setWebsite(&quot;http://www.example.com&quot;);<br />
clientData.setDefaultScope(&quot;read_contacts write_contacts&quot;);<br />
clientData.setRedirectURIs(redirectURIs);<br />
return clientData;<br />
}<br />
<br />
private static byte[] loadIcon() throws FileNotFoundException {<br />
byte[] iconBytes = null;<br />
// TODO: change this path accordingly<br />
try (FileInputStream fis = new FileInputStream(&quot;/path/to/icon.png&quot;)) {<br />
byte[] buf = new byte[4096];<br />
int len = fis.read(buf);<br />
ByteArrayOutputStream baos = new ByteArrayOutputStream();<br />
do {<br />
baos.write(buf, 0, len);<br />
len = fis.read(buf);<br />
} while (len &gt;= 0);<br />
<br />
iconBytes = baos.toByteArray();<br />
} catch (IOException e) {<br />
// closing the input stream failed - ignore...<br />
}<br />
<br />
return iconBytes;<br />
}<br />
<br />
}</pre><br />
<br />
== SOAP Provisioning ==<br />
<br />
Besides RMI all provisioning calls are also available via [http://oxpedia.org/wiki/index.php?title=Open-Xchange_Provisioning_using_SOAP SOAP]. After everything orderly set up you can obtain the according WSDL via <code>https://ox-prov.coolhosting.me/webservices/OAuthClientService?wsdl</code>, while <code>ox-prov.coolhosting.me</code> denotes your provisioning node. Below you find example requests and responses for all operations.<br />
<br />
All operations require the master admin credentials. Icons raw bytes are always required/returned as a Base64-encoded strings.<br />
<br />
=== List Clients ===<br />
<br />
List all clients of a certain context group. Only IDs and names are returned.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:listClients&gt;<br />
&lt;soap:contextGroup&gt;default&lt;/soap:contextGroup&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:listClients&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;listClientsResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;client&gt;<br />
&lt;id&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/id&gt;<br />
&lt;name&gt;Example.com&lt;/name&gt;<br />
&lt;/client&gt;<br />
&lt;client&gt;<br />
&lt;id&gt;ZGVmYXVsdA/0b44694662564c1fb2c1bfc008e247d5b27dd32632734f879d8023aa640dd1ae&lt;/id&gt;<br />
&lt;name&gt;Another App&lt;/name&gt;<br />
&lt;/client&gt;<br />
&lt;/listClientsResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
=== Get Client Details ===<br />
<br />
Get the details of a client by its ID.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:getClientById&gt;<br />
&lt;soap:clientId&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/soap:clientId&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:getClientById&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;getClientByIdResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;client&gt;<br />
&lt;id&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/id&gt;<br />
&lt;name&gt;Example.com&lt;/name&gt;<br />
&lt;description&gt;Example.com is the superior App Suite extension!&lt;/description&gt;<br />
&lt;contactAddress&gt;contact@example.com&lt;/contactAddress&gt;<br />
&lt;website&gt;https://example.com&lt;/website&gt;<br />
&lt;defaultScope&gt;write_contacts read_contacts&lt;/defaultScope&gt;<br />
&lt;redirectURI&gt;https://app.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;redirectURI&gt;https://testbed.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;secret&gt;dc989e068a7943dc800069b807fd6fc9b6ef3defa43d4717ba66c0a275c0697f&lt;/secret&gt;<br />
&lt;registrationDate&gt;1429028393472&lt;/registrationDate&gt;<br />
&lt;enabled&gt;true&lt;/enabled&gt;<br />
&lt;icon&gt;<br />
&lt;mimeType&gt;image/jpg&lt;/mimeType&gt;<br />
&lt;data&gt;<br />
/9j/4AAQSkZJRgABAgAAAQABAAD/7QCEUGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAAGccAigAYkZC<br />
TUQwMTAwMGE4NjAxMDAwMGUxMDEwMDAwMmQwMjAwMDA1OTAyMDAwMDhlMDIwMDAwMDAwMzAwMDA1<br />
NDAzMDAwMDhlMDMwMDAwY2IwMzAwMDAwOTA0MDAwMDg2MDQwMDAwAP/bAEMABgQFBgUEBgYFBgcH<br />
BggKEAoKCQkKFA4PDBAXFBgYFxQWFhodJR8aGyMcFhYgLCAjJicpKikZHy0wLSgwJSgpKP/bAEMB<br />
BwcHCggKEwoKEygaFhooKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgo<br />
KCgoKCgoKP/CABEIADIAMgMAIgABEQECEQH/xAAZAAADAQEBAAAAAAAAAAAAAAAAAQIDBgX/xAAY<br />
AQEBAQEBAAAAAAAAAAAAAAABAAIDBf/EABgBAQEBAQEAAAAAAAAAAAAAAAEAAgMF/9oADAMAAAER<br />
AhEAAAHx9cNfQ8/a8qSoJpEg4dZyHW8+mstZ0+c6Lld4ZBrOTljo821ylQIqWmLaaIAgCv/EABwQ<br />
AQACAwADAAAAAAAAAAAAAAQBAwACECAwQP/aAAgBAAABBQKMjwnkeiSlOMlIV2lKdGXkoGbedZjk<br />
qIkQ7gEtOwxtbGHYWfn/AP/EABoRAAICAwAAAAAAAAAAAAAAAAACEUEgITD/2gAIAQIRAT8BwWDV<br />
jRXL/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAIRQSAhMP/aAAgBAREBPwHBpN0JN8v/xAAjEAACAgED<br />
AwUAAAAAAAAAAAACAwERAAQhMRASUhMUMEBh/9oACAEAAAY/AvnQ3UeqZM8ZyVLF4lV3M4xNyGqG<br />
452nI9zMnqC4EZwe0amt/wB6oVqCYsleMZLVscZVVSOMaNs1R78bRnbrLB48GMfY/8QAIhABAQEA<br />
AQMDBQAAAAAAAAAAAQARMRAhUSBBYTCxwfDx/9oACAEAAAE/IegW+kGG2WW2GDsEeLNNt4a4eEXr<br />
0F1j7h+Js7jYp/PmO2LD3lbEY6A5dwy1Qz7pB2k9zNXjfH3hXkLT9+Jd/NsQw22y2x136f8A/9oA<br />
DAMAAAERAhEAABCmLro7VXJNxDxan8P/xAAeEQACAgEFAQAAAAAAAAAAAAAAAREhMRAgQWHwUf/a<br />
AAgBAhEBPxBjEiBLTnsSrTv30uXH2SBkEaPZ/8QAHhEAAgIBBQEAAAAAAAAAAAAAAREAIUEQIFGB<br />
ofD/2gAIAQERAT8QEBhOh0TWVCb2wvuJQbvzqOCOPd//xAAeEAEAAgICAwEAAAAAAAAAAAABABEh<br />
MRBBIFFhcf/aAAgBAAABPxBxRwhYpcXMHhJXKickhiCmsBi85lCK1ihDVt7OpbSJ1bS51jOxsh64<br />
V5/uLp2tuCWgBK57D1wURjVqLpt04TPTcFAChCyO6M47agH1wzs1XS8pmnRo1MIm32jNPa/R9UIE<br />
A1Zp++MBDyCgweFxeCEPH//Z<br />
&lt;/data&gt;<br />
&lt;/icon&gt;<br />
&lt;/client&gt;<br />
&lt;/getClientByIdResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
=== Register Client ===<br />
<br />
Register a new client. The response contains the whole client data along with the generated client ID and secret.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:registerClient&gt;<br />
&lt;soap:contextGroup&gt;default&lt;/soap:contextGroup&gt;<br />
&lt;soap:clientData&gt;<br />
&lt;!-- All client data fields must be set during registration! --&gt;<br />
&lt;soap:name&gt;Example.com&lt;/soap:name&gt;<br />
&lt;soap:description&gt;Example.com is the superior App Suite extension!&lt;/soap:description&gt;<br />
&lt;soap:contactAddress&gt;contact@example.com&lt;/soap:contactAddress&gt;<br />
&lt;soap:website&gt;https://example.com&lt;/soap:website&gt;<br />
&lt;!-- Scope is required as a space-separated string --&gt;<br />
&lt;soap:defaultScope&gt;read_contacts write_contacts&lt;/soap:defaultScope&gt;<br />
&lt;!-- You may define one or more redirect URIs --&gt;<br />
&lt;soap:redirectURI&gt;https://app.example.com/oauth2&lt;/soap:redirectURI&gt;<br />
&lt;soap:redirectURI&gt;https://testbed.example.com/oauth2&lt;/soap:redirectURI&gt;<br />
&lt;soap:icon&gt;<br />
&lt;soap:mimeType&gt;image/jpg&lt;/soap:mimeType&gt;<br />
&lt;data&gt;<br />
/9j/4AAQSkZJRgABAgAAAQABAAD/7QCEUGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAAGccAigAYkZC<br />
TUQwMTAwMGE4NjAxMDAwMGUxMDEwMDAwMmQwMjAwMDA1OTAyMDAwMDhlMDIwMDAwMDAwMzAwMDA1<br />
NDAzMDAwMDhlMDMwMDAwY2IwMzAwMDAwOTA0MDAwMDg2MDQwMDAwAP/bAEMABgQFBgUEBgYFBgcH<br />
BggKEAoKCQkKFA4PDBAXFBgYFxQWFhodJR8aGyMcFhYgLCAjJicpKikZHy0wLSgwJSgpKP/bAEMB<br />
BwcHCggKEwoKEygaFhooKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgo<br />
KCgoKCgoKP/CABEIADIAMgMAIgABEQECEQH/xAAZAAADAQEBAAAAAAAAAAAAAAAAAQIDBgX/xAAY<br />
AQEBAQEBAAAAAAAAAAAAAAABAAIDBf/EABgBAQEBAQEAAAAAAAAAAAAAAAEAAgMF/9oADAMAAAER<br />
AhEAAAHx9cNfQ8/a8qSoJpEg4dZyHW8+mstZ0+c6Lld4ZBrOTljo821ylQIqWmLaaIAgCv/EABwQ<br />
AQACAwADAAAAAAAAAAAAAAQBAwACECAwQP/aAAgBAAABBQKMjwnkeiSlOMlIV2lKdGXkoGbedZjk<br />
qIkQ7gEtOwxtbGHYWfn/AP/EABoRAAICAwAAAAAAAAAAAAAAAAACEUEgITD/2gAIAQIRAT8BwWDV<br />
jRXL/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAIRQSAhMP/aAAgBAREBPwHBpN0JN8v/xAAjEAACAgED<br />
AwUAAAAAAAAAAAACAwERAAQhMRASUhMUMEBh/9oACAEAAAY/AvnQ3UeqZM8ZyVLF4lV3M4xNyGqG<br />
452nI9zMnqC4EZwe0amt/wB6oVqCYsleMZLVscZVVSOMaNs1R78bRnbrLB48GMfY/8QAIhABAQEA<br />
AQMDBQAAAAAAAAAAAQARMRAhUSBBYTCxwfDx/9oACAEAAAE/IegW+kGG2WW2GDsEeLNNt4a4eEXr<br />
0F1j7h+Js7jYp/PmO2LD3lbEY6A5dwy1Qz7pB2k9zNXjfH3hXkLT9+Jd/NsQw22y2x136f8A/9oA<br />
DAMAAAERAhEAABCmLro7VXJNxDxan8P/xAAeEQACAgEFAQAAAAAAAAAAAAAAAREhMRAgQWHwUf/a<br />
AAgBAhEBPxBjEiBLTnsSrTv30uXH2SBkEaPZ/8QAHhEAAgIBBQEAAAAAAAAAAAAAAREAIUEQIFGB<br />
ofD/2gAIAQERAT8QEBhOh0TWVCb2wvuJQbvzqOCOPd//xAAeEAEAAgICAwEAAAAAAAAAAAABABEh<br />
MRBBIFFhcf/aAAgBAAABPxBxRwhYpcXMHhJXKickhiCmsBi85lCK1ihDVt7OpbSJ1bS51jOxsh64<br />
V5/uLp2tuCWgBK57D1wURjVqLpt04TPTcFAChCyO6M47agH1wzs1XS8pmnRo1MIm32jNPa/R9UIE<br />
A1Zp++MBDyCgweFxeCEPH//Z<br />
&lt;/data&gt;<br />
&lt;/soap:icon&gt;<br />
&lt;/soap:clientData&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:registerClient&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;registerClientResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;client&gt;<br />
&lt;id&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/id&gt;<br />
&lt;name&gt;Example.com&lt;/name&gt;<br />
&lt;description&gt;Example.com is the superior App Suite extension!&lt;/description&gt;<br />
&lt;contactAddress&gt;contact@example.com&lt;/contactAddress&gt;<br />
&lt;website&gt;https://example.com&lt;/website&gt;<br />
&lt;defaultScope&gt;write_contacts read_contacts&lt;/defaultScope&gt;<br />
&lt;redirectURI&gt;https://app.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;redirectURI&gt;https://testbed.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;secret&gt;dc989e068a7943dc800069b807fd6fc9b6ef3defa43d4717ba66c0a275c0697f&lt;/secret&gt;<br />
&lt;registrationDate&gt;1429028393472&lt;/registrationDate&gt;<br />
&lt;enabled&gt;true&lt;/enabled&gt;<br />
&lt;icon&gt;<br />
&lt;mimeType&gt;image/jpg&lt;/mimeType&gt;<br />
&lt;data&gt;<br />
/9j/4AAQSkZJRgABAgAAAQABAAD/7QCEUGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAAGccAigAYkZC<br />
TUQwMTAwMGE4NjAxMDAwMGUxMDEwMDAwMmQwMjAwMDA1OTAyMDAwMDhlMDIwMDAwMDAwMzAwMDA1<br />
NDAzMDAwMDhlMDMwMDAwY2IwMzAwMDAwOTA0MDAwMDg2MDQwMDAwAP/bAEMABgQFBgUEBgYFBgcH<br />
BggKEAoKCQkKFA4PDBAXFBgYFxQWFhodJR8aGyMcFhYgLCAjJicpKikZHy0wLSgwJSgpKP/bAEMB<br />
BwcHCggKEwoKEygaFhooKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgo<br />
KCgoKCgoKP/CABEIADIAMgMAIgABEQECEQH/xAAZAAADAQEBAAAAAAAAAAAAAAAAAQIDBgX/xAAY<br />
AQEBAQEBAAAAAAAAAAAAAAABAAIDBf/EABgBAQEBAQEAAAAAAAAAAAAAAAEAAgMF/9oADAMAAAER<br />
AhEAAAHx9cNfQ8/a8qSoJpEg4dZyHW8+mstZ0+c6Lld4ZBrOTljo821ylQIqWmLaaIAgCv/EABwQ<br />
AQACAwADAAAAAAAAAAAAAAQBAwACECAwQP/aAAgBAAABBQKMjwnkeiSlOMlIV2lKdGXkoGbedZjk<br />
qIkQ7gEtOwxtbGHYWfn/AP/EABoRAAICAwAAAAAAAAAAAAAAAAACEUEgITD/2gAIAQIRAT8BwWDV<br />
jRXL/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAIRQSAhMP/aAAgBAREBPwHBpN0JN8v/xAAjEAACAgED<br />
AwUAAAAAAAAAAAACAwERAAQhMRASUhMUMEBh/9oACAEAAAY/AvnQ3UeqZM8ZyVLF4lV3M4xNyGqG<br />
452nI9zMnqC4EZwe0amt/wB6oVqCYsleMZLVscZVVSOMaNs1R78bRnbrLB48GMfY/8QAIhABAQEA<br />
AQMDBQAAAAAAAAAAAQARMRAhUSBBYTCxwfDx/9oACAEAAAE/IegW+kGG2WW2GDsEeLNNt4a4eEXr<br />
0F1j7h+Js7jYp/PmO2LD3lbEY6A5dwy1Qz7pB2k9zNXjfH3hXkLT9+Jd/NsQw22y2x136f8A/9oA<br />
DAMAAAERAhEAABCmLro7VXJNxDxan8P/xAAeEQACAgEFAQAAAAAAAAAAAAAAAREhMRAgQWHwUf/a<br />
AAgBAhEBPxBjEiBLTnsSrTv30uXH2SBkEaPZ/8QAHhEAAgIBBQEAAAAAAAAAAAAAAREAIUEQIFGB<br />
ofD/2gAIAQERAT8QEBhOh0TWVCb2wvuJQbvzqOCOPd//xAAeEAEAAgICAwEAAAAAAAAAAAABABEh<br />
MRBBIFFhcf/aAAgBAAABPxBxRwhYpcXMHhJXKickhiCmsBi85lCK1ihDVt7OpbSJ1bS51jOxsh64<br />
V5/uLp2tuCWgBK57D1wURjVqLpt04TPTcFAChCyO6M47agH1wzs1XS8pmnRo1MIm32jNPa/R9UIE<br />
A1Zp++MBDyCgweFxeCEPH//Z<br />
&lt;/data&gt;<br />
&lt;/icon&gt;<br />
&lt;/client&gt;<br />
&lt;/registerClientResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
=== Update Client ===<br />
<br />
Already registered clients can be modified. The response contains the whole client data with all changes applied.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:updateClient&gt;<br />
&lt;soap:clientId&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/soap:clientId&gt;<br />
&lt;soap:clientData&gt;<br />
&lt;!-- All client data fields that are set will be updated.<br />
If you want to change the redirect URIs, you must specify all of them! <br />
All URIs are overridden by the data of this request. If you don't specify<br />
any redirectURI element, the existing ones are kept. --&gt;<br />
&lt;!-- Extend default scope --&gt;<br />
&lt;soap:defaultScope&gt;read_contacts write_contacts read_calendar write_calendar&lt;/soap:defaultScope&gt;<br />
&lt;/soap:clientData&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:updateClient&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;updateClientResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;client&gt;<br />
&lt;id&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/id&gt;<br />
&lt;name&gt;Example.com&lt;/name&gt;<br />
&lt;description&gt;Example.com is the superior App Suite extension!&lt;/description&gt;<br />
&lt;contactAddress&gt;contact@example.com&lt;/contactAddress&gt;<br />
&lt;website&gt;https://example.com&lt;/website&gt;<br />
&lt;defaultScope&gt;write_contacts write_calendar read_contacts read_calendar&lt;/defaultScope&gt;<br />
&lt;redirectURI&gt;https://app.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;redirectURI&gt;https://testbed.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;secret&gt;dc989e068a7943dc800069b807fd6fc9b6ef3defa43d4717ba66c0a275c0697f&lt;/secret&gt;<br />
&lt;registrationDate&gt;1429028393472&lt;/registrationDate&gt;<br />
&lt;enabled&gt;true&lt;/enabled&gt;<br />
&lt;icon&gt;<br />
&lt;mimeType&gt;image/jpg&lt;/mimeType&gt;<br />
&lt;data&gt;<br />
/9j/4AAQSkZJRgABAgAAAQABAAD/7QCEUGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAAGccAigAYkZC<br />
TUQwMTAwMGE4NjAxMDAwMGUxMDEwMDAwMmQwMjAwMDA1OTAyMDAwMDhlMDIwMDAwMDAwMzAwMDA1<br />
NDAzMDAwMDhlMDMwMDAwY2IwMzAwMDAwOTA0MDAwMDg2MDQwMDAwAP/bAEMABgQFBgUEBgYFBgcH<br />
BggKEAoKCQkKFA4PDBAXFBgYFxQWFhodJR8aGyMcFhYgLCAjJicpKikZHy0wLSgwJSgpKP/bAEMB<br />
BwcHCggKEwoKEygaFhooKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgo<br />
KCgoKCgoKP/CABEIADIAMgMAIgABEQECEQH/xAAZAAADAQEBAAAAAAAAAAAAAAAAAQIDBgX/xAAY<br />
AQEBAQEBAAAAAAAAAAAAAAABAAIDBf/EABgBAQEBAQEAAAAAAAAAAAAAAAEAAgMF/9oADAMAAAER<br />
AhEAAAHx9cNfQ8/a8qSoJpEg4dZyHW8+mstZ0+c6Lld4ZBrOTljo821ylQIqWmLaaIAgCv/EABwQ<br />
AQACAwADAAAAAAAAAAAAAAQBAwACECAwQP/aAAgBAAABBQKMjwnkeiSlOMlIV2lKdGXkoGbedZjk<br />
qIkQ7gEtOwxtbGHYWfn/AP/EABoRAAICAwAAAAAAAAAAAAAAAAACEUEgITD/2gAIAQIRAT8BwWDV<br />
jRXL/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAIRQSAhMP/aAAgBAREBPwHBpN0JN8v/xAAjEAACAgED<br />
AwUAAAAAAAAAAAACAwERAAQhMRASUhMUMEBh/9oACAEAAAY/AvnQ3UeqZM8ZyVLF4lV3M4xNyGqG<br />
452nI9zMnqC4EZwe0amt/wB6oVqCYsleMZLVscZVVSOMaNs1R78bRnbrLB48GMfY/8QAIhABAQEA<br />
AQMDBQAAAAAAAAAAAQARMRAhUSBBYTCxwfDx/9oACAEAAAE/IegW+kGG2WW2GDsEeLNNt4a4eEXr<br />
0F1j7h+Js7jYp/PmO2LD3lbEY6A5dwy1Qz7pB2k9zNXjfH3hXkLT9+Jd/NsQw22y2x136f8A/9oA<br />
DAMAAAERAhEAABCmLro7VXJNxDxan8P/xAAeEQACAgEFAQAAAAAAAAAAAAAAAREhMRAgQWHwUf/a<br />
AAgBAhEBPxBjEiBLTnsSrTv30uXH2SBkEaPZ/8QAHhEAAgIBBQEAAAAAAAAAAAAAAREAIUEQIFGB<br />
ofD/2gAIAQERAT8QEBhOh0TWVCb2wvuJQbvzqOCOPd//xAAeEAEAAgICAwEAAAAAAAAAAAABABEh<br />
MRBBIFFhcf/aAAgBAAABPxBxRwhYpcXMHhJXKickhiCmsBi85lCK1ihDVt7OpbSJ1bS51jOxsh64<br />
V5/uLp2tuCWgBK57D1wURjVqLpt04TPTcFAChCyO6M47agH1wzs1XS8pmnRo1MIm32jNPa/R9UIE<br />
A1Zp++MBDyCgweFxeCEPH//Z<br />
&lt;/data&gt;<br />
&lt;/icon&gt;<br />
&lt;/client&gt;<br />
&lt;/updateClientResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
=== Revoke Secret ===<br />
<br />
A clients secret can be revoked. This leads to a revocation of all grants authorized by any users for this client. A new secret is generated and part of the response.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:revokeClientSecret&gt;<br />
&lt;soap:clientId&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/soap:clientId&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:revokeClientSecret&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;revokeClientSecretResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;client&gt;<br />
&lt;id&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/id&gt;<br />
&lt;name&gt;Example.com&lt;/name&gt;<br />
&lt;description&gt;Example.com is the superior App Suite extension!&lt;/description&gt;<br />
&lt;contactAddress&gt;contact@example.com&lt;/contactAddress&gt;<br />
&lt;website&gt;https://example.com&lt;/website&gt;<br />
&lt;defaultScope&gt;write_contacts write_calendar read_contacts read_calendar&lt;/defaultScope&gt;<br />
&lt;redirectURI&gt;https://app.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;redirectURI&gt;https://testbed.example.com/oauth2&lt;/redirectURI&gt;<br />
&lt;secret&gt;67726d3b86854fc594a19b2251f7e668ece7e9205f11431c92f3f2a6bd2295fc&lt;/secret&gt;<br />
&lt;registrationDate&gt;1429028393472&lt;/registrationDate&gt;<br />
&lt;enabled&gt;true&lt;/enabled&gt;<br />
&lt;icon&gt;<br />
&lt;mimeType&gt;image/jpg&lt;/mimeType&gt;<br />
&lt;data&gt;<br />
/9j/4AAQSkZJRgABAgAAAQABAAD/7QCEUGhvdG9zaG9wIDMuMAA4QklNBAQAAAAAAGccAigAYkZC<br />
TUQwMTAwMGE4NjAxMDAwMGUxMDEwMDAwMmQwMjAwMDA1OTAyMDAwMDhlMDIwMDAwMDAwMzAwMDA1<br />
NDAzMDAwMDhlMDMwMDAwY2IwMzAwMDAwOTA0MDAwMDg2MDQwMDAwAP/bAEMABgQFBgUEBgYFBgcH<br />
BggKEAoKCQkKFA4PDBAXFBgYFxQWFhodJR8aGyMcFhYgLCAjJicpKikZHy0wLSgwJSgpKP/bAEMB<br />
BwcHCggKEwoKEygaFhooKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgo<br />
KCgoKCgoKP/CABEIADIAMgMAIgABEQECEQH/xAAZAAADAQEBAAAAAAAAAAAAAAAAAQIDBgX/xAAY<br />
AQEBAQEBAAAAAAAAAAAAAAABAAIDBf/EABgBAQEBAQEAAAAAAAAAAAAAAAEAAgMF/9oADAMAAAER<br />
AhEAAAHx9cNfQ8/a8qSoJpEg4dZyHW8+mstZ0+c6Lld4ZBrOTljo821ylQIqWmLaaIAgCv/EABwQ<br />
AQACAwADAAAAAAAAAAAAAAQBAwACECAwQP/aAAgBAAABBQKMjwnkeiSlOMlIV2lKdGXkoGbedZjk<br />
qIkQ7gEtOwxtbGHYWfn/AP/EABoRAAICAwAAAAAAAAAAAAAAAAACEUEgITD/2gAIAQIRAT8BwWDV<br />
jRXL/8QAGhEAAgIDAAAAAAAAAAAAAAAAAAIRQSAhMP/aAAgBAREBPwHBpN0JN8v/xAAjEAACAgED<br />
AwUAAAAAAAAAAAACAwERAAQhMRASUhMUMEBh/9oACAEAAAY/AvnQ3UeqZM8ZyVLF4lV3M4xNyGqG<br />
452nI9zMnqC4EZwe0amt/wB6oVqCYsleMZLVscZVVSOMaNs1R78bRnbrLB48GMfY/8QAIhABAQEA<br />
AQMDBQAAAAAAAAAAAQARMRAhUSBBYTCxwfDx/9oACAEAAAE/IegW+kGG2WW2GDsEeLNNt4a4eEXr<br />
0F1j7h+Js7jYp/PmO2LD3lbEY6A5dwy1Qz7pB2k9zNXjfH3hXkLT9+Jd/NsQw22y2x136f8A/9oA<br />
DAMAAAERAhEAABCmLro7VXJNxDxan8P/xAAeEQACAgEFAQAAAAAAAAAAAAAAAREhMRAgQWHwUf/a<br />
AAgBAhEBPxBjEiBLTnsSrTv30uXH2SBkEaPZ/8QAHhEAAgIBBQEAAAAAAAAAAAAAAREAIUEQIFGB<br />
ofD/2gAIAQERAT8QEBhOh0TWVCb2wvuJQbvzqOCOPd//xAAeEAEAAgICAwEAAAAAAAAAAAABABEh<br />
MRBBIFFhcf/aAAgBAAABPxBxRwhYpcXMHhJXKickhiCmsBi85lCK1ihDVt7OpbSJ1bS51jOxsh64<br />
V5/uLp2tuCWgBK57D1wURjVqLpt04TPTcFAChCyO6M47agH1wzs1XS8pmnRo1MIm32jNPa/R9UIE<br />
A1Zp++MBDyCgweFxeCEPH//Z<br />
&lt;/data&gt;<br />
&lt;/icon&gt;<br />
&lt;/client&gt;<br />
&lt;/revokeClientSecretResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
=== Unregister Client ===<br />
<br />
Of course clients can be unregistered. This leads to a revocation of all grants authorized by any users for this client. If the client ID is invalid, the responses success value will be <code>false</code>.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:unregisterClient&gt;<br />
&lt;soap:clientId&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/soap:clientId&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:unregisterClient&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;unregisterClientResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;success&gt;true&lt;/success&gt;<br />
&lt;/unregisterClientResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
=== Disable Client ===<br />
<br />
Enabled clients can be disabled. This leads to a revocation of all grants authorized by any users for this client and no further grants can be requested. If the client was already disabled, the responses success value will be <code>false</code>.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:disableClient&gt;<br />
&lt;soap:clientId&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/soap:clientId&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:disableClient&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;disableClientResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;success&gt;true&lt;/success&gt;<br />
&lt;/disableClientResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
=== Enable Client ===<br />
<br />
Disabled clients can of course be enabled again. If the client was already enabled, the responses success value will be <code>false</code>.<br />
<br />
==== Request ====<br />
<br />
<pre>&lt;soapenv:Envelope xmlns:soapenv=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;<br />
xmlns:soap=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;soapenv:Header/&gt;<br />
&lt;soapenv:Body&gt;<br />
&lt;soap:enableClient&gt;<br />
&lt;soap:clientId&gt;ZGVmYXVsdA/2b6d423de5344ed9bd67f95eb6917507f7c8018a5c0a47a1a4ba1bae14615ee6&lt;/soap:clientId&gt;<br />
&lt;soap:credentials&gt;<br />
&lt;soap:login&gt;oxadminmaster&lt;/soap:login&gt;<br />
&lt;soap:password&gt;secret&lt;/soap:password&gt;<br />
&lt;/soap:credentials&gt;<br />
&lt;/soap:enableClient&gt;<br />
&lt;/soapenv:Body&gt;<br />
&lt;/soapenv:Envelope&gt;</pre><br />
<br />
==== Response ====<br />
<br />
<pre>&lt;soap:Envelope xmlns:soap=&quot;http://schemas.xmlsoap.org/soap/envelope/&quot;&gt;<br />
&lt;soap:Body&gt;<br />
&lt;enableClientResponse xmlns=&quot;http://soap.provider.oauth.openexchange.com&quot;&gt;<br />
&lt;success&gt;true&lt;/success&gt;<br />
&lt;/enableClientResponse&gt;<br />
&lt;/soap:Body&gt;<br />
&lt;/soap:Envelope&gt;</pre><br />
<br />
<br />
== Using an external authorization server ==<br />
<br />
When using an external authorization server, the internal client and grant management are deactivated. The according provisioning interfaces will not be available and the "External Apps" section within the App Suite settings page will not show up. The whole client and grant management will be off-loaded to the external identity management system.<br />
<br />
You need to deactivate the internal authorization server, by setting <code>com.openexchange.oauth.provider.isAuthorizationServer</code> in <code>/opt/open-xchange/etc/oauth-provider.properties</code> to <code>false</code>. Additionally you need to provide an implementation of <code>com.openexchange.oauth.provider.authorizationserver.spi.OAuthAuthorizationService</code> as OSGi service. Its purpose is to validate the access tokens of incoming requests and to identify the according OX user. The service provider interface is contained in bundle <code>com.openexchange.oauth.provider</code>. <br />
<br />
=== Example ===<br />
<br />
An example implementation using the [http://wso2.com/products/identity-server/ WSO2 Identity Server 5.1.0] can be found here: https://code.open-xchange.com/git/examples/backend-samples as project <code>com.openexchange.oauth.provider.wso2</code>. It is based on this [http://shanakaweerasinghe.blogspot.de/2016_01_01_archive.html blog post].<br />
<br />
If you want to test the WSO2 provider in production, you need to create a proper bundle JAR and install it to your OX middleware OSGi runtime. The endpoint of the WSO2 <code>OAuth2TokenValidationService</code> must be configured via <code>/opt/open-xchange/etc/wso2-oauth.properties</code>. Example content:<br />
<pre><br />
com.openexchange.oauth.provider.wso2.tokenEndpoint = https://localhost:9443/services/OAuth2TokenValidationService<br />
com.openexchange.oauth.provider.wso2.apiUser = admin<br />
com.openexchange.oauth.provider.wso2.apiPassword = admin<br />
</pre><br />
<br />
The WSO2 identity server also needs some configuration:<br />
<br />
* Edit <code>wso2is-5.1.0/repository/conf/identity/identity.xml</code> and change the <code><Enabled></code> element of <code><AuthorizationContextTokenGeneration></code> to <code>true</code><br />
* Edit and change <code><HideAdminServiceWSDLs></code> to <code>false</code><br />
* Restart the server and login as admin to the management console<br />
* Add a new service provider with name "OAuth" and configure OAuth as inbound authentication mechanism<br />
* OAuth Version: 2.0<br />
* Callback Url: depends on your application<br />
* Allowed Grant Types: Code and Refresh Token<br />
* Copy the shown client credentials and configure your test application accordingly<br />
* Add a new user<br />
* Assign the role "Application/OAuth"<br />
* Edit its profile and configure the email address to match the pattern <code><ox-user-name>@<ox-context-name></code>. The context name must end with a TLD, you'll need an according login mapping within OX.<br />
<br />
You can now configure your client with the according authorization and token endpoint URLs:<br />
<br />
* Authorization endpoint: <code>https://<wso2-host>:9443/oauth2/authorize</code><br />
* Token endpoint: <code>https://<wso2-host>:9443/oauth2/token</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=21172HTTP API2015-12-16T13:55:26Z<p>Steffen.templin: /* Configuration */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
DISCLAIMER: This request MUST NOT be used by some server side instance. If some server side instance uses this request to create a session for a browser on some client machine, then you have to transfer the full URL with server and client token over some connection to the client. This creates a VULNERABILITY if this is done. The token login method is only secure if this request is already sent from the same machine that later runs the browser using the created 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 318 || account_id || String || Will be <code>null</code> if the folder does not belong to any account<br />
(i.e. if its module doesn't support multiple accounts), is a virtual folder or an account-agnostic system folder. Since 7.8.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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 this parameter is specified, then the parameter order must be also specified. Since 7.8.1: If this parameter is missing, response is sorted by a user-specific use count of contacts, ID of contacts' parent folder and display name.<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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
=== Acknowledge receipt ===<br />
<br />
PUT <code>/ajax/mail?action=receipt_ack</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request Body: A JSON object containing the "from address", the id of the folder and the mail id: e.g.: {"from":"mymail@domain.com","folder":"default0/INBOX","id":"1234"}<br />
<br />
Response: A JSON object with an empty data field if everything went well or a JSON object containing the error information.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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 />
=== Move one or more infoitems via PUT ===<br />
<br />
PUT <code>/ajax/infostore?action=move</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>folder</code> – ID of the destination folder.<br />
<br />
Request body: A JSON array consisting of JSON objects each referencing to an existing infoitem that is supposed to be moved to the destination folder<br />
<br />
<pre><br />
[<br />
{"id":"31841/36639", "folder":"31841"},<br />
{"id":"31841/36641", "folder":"31841"}<br />
]<br />
</pre><br />
<br />
Response: A JSON array consisting of those identifiers that could not be moved (due to a conflict) or an empty JSON array if everything went fine<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
== Module Halo ==<br />
<br />
=== Investigate contact ===<br />
<br />
PUT /appsuite/api/halo/contact?action=investigate<br />
<br />
The investigate action provides access to different halo providers. <br />
Each provider requires an own set of parameters and also provides different results. <br />
The following section describes some but not necessarily all of this providers.<br />
Each request contains the following common parameters:<br />
<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>provider</code> - The provider to use.<br />
* <code>timezone</code> - (optional) The timezone.<br />
<br />
<br />
In addition to this parameters a contact must be defined. This can be done either with at least one of the following parameters:<br />
<br />
* <code>email1</code><br />
* <code>email2</code><br />
* <code>email3</code><br />
* <code>internal_userid</code><br />
<br />
or within the request body.<br />
<br />
Request body:<br />
<br />
Instead of the contact parameters one can send a JSON object within the body of the request. This body describes the contact.<br />
If used, it must contain at least one of the fields shown below. If the requests contains a body, the contact specific parameters are ignored. <br />
It is also possible to provide more contact information. Empty fields are filled up with this values.<br />
<br />
<br />
JSON object:<br />
<pre><br />
{<br />
"contact_id":12345<br />
"internal_userid":12345<br />
"email1": mail1@domain.com<br />
"email2": mail2@domain2.com<br />
"email3": mail3@domain3.com<br />
}<br />
</pre><br />
<br />
Request response: <br />
The request responds with a JSON object. The content and structure of this object depends on the chosen provider. <br />
In each case the response contains only data known to the server. Therefore some or all fields may be null.<br />
<br />
<br />
<strong> Provider: com.openexchange.halo.contacts </strong><br />
<br />
Request parameters:<br />
<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 response:<br />
<br />
A JSON array with the contact informations specified by the columns parameter. <br />
<br />
<br />
<strong> Provider: com.openexchange.halo.appointments </strong><br />
<br />
Requests parameters:<br />
<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>start</code> - The start point in milliseconds since 01.01.1970<br />
* <code>end</code> - The end point in milliseconds since 01.01.1970<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 response:<br />
<br />
A JSON array of appointments. Each appointment contains the fields specified by the columns parameter. <br />
<br />
<br />
<strong> Provider: com.openexchange.halo.mail </strong><br />
<br />
Request parameters:<br />
<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>limit</code> - The maximum number of mails within the result.<br />
<br />
Request response: <br />
<br />
A JSON array of mails. Each mail contains the fields specified by the columns parameter.<br />
<br />
=== Get halo services ===<br />
<br />
GET /appsuite/api/halo/contact?action=services<br />
<br />
Request parameter: <br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
<br />
Request response:<br />
<br />
A JSON object with a "data" field which contains an array of all available halo providers.<br />
<br />
=== Get contact picture ===<br />
<br />
GET /appsuite/api/halo/contact/picture<br />
* <code>session</code> - (optional) falls back to the public session cookie<br />
* <code>internal_userid</code> - (optional) The internal user id of a user whose picture you want to load<br />
* <code>userid</code> - (optional) an alias for internal_userid<br />
* <code>user_id</code> - (optional) an alias for internal_userid<br />
* <code>id</code> - (optional) a contact id<br />
* <code>email</code> - (optional) an email to search for. Will pick global address book matches before regular matches. After that picks the most recently changed contact<br />
* <code>email1</code> - (optional) an alias for email<br />
* <code>email2</code> - (optional) another email address to use to find matches<br />
* <code>email3</code> - (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 />
== 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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
=== 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. If the user is not allowed to search in any module, the value will be null.<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password or 'null' if the password wasn't set before (especially for guest users)<br />
|-<br />
| new_password || String || The new password the user wants to set or 'null' to remove the password (especially for guest users)<br />
|-<br />
|}<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account in the scope of its file storage service (Infostore, Dropbox.com, Google OneDrive etc.). This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage service this account belongs to <br />
|-<br />
| qualifiedId || String || Identifies a given file storage account globally, i.e. accross all file storage services. This is not writeable and is generated by the server <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 />
| rootFolder || String || ID of the accounts root folder within the folder tree. This is not writeable and is generated by the server <br />
|-<br />
| isDefaultAccount || Boolean || Whether this account is the users default account. Exactly one account will have this flag set to <code>true</code>.<br />
|-<br />
| configuration || Object || Configuration data according to the formDescription of the relevant file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the relative (in context of the according file storage service) identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20548HTTP API2015-09-22T14:31:14Z<p>Steffen.templin: /* Create a folder */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 318 || account_id || String || Will be <code>null</code> if the folder does not belong to any account<br />
(i.e. if its module doesn't support multiple accounts), is a virtual folder or an account-agnostic system folder. Since 7.8.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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
=== 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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password or 'null' if the password wasn't set before (especially for guest users)<br />
|-<br />
| new_password || String || The new password the user wants to set or 'null' to remove the password (especially for guest users)<br />
|-<br />
|}<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account in the scope of its file storage service (Infostore, Dropbox.com, Google OneDrive etc.). This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage service this account belongs to <br />
|-<br />
| qualifiedId || String || Identifies a given file storage account globally, i.e. accross all file storage services. This is not writeable and is generated by the server <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 />
| rootFolder || String || ID of the accounts root folder within the folder tree. This is not writeable and is generated by the server <br />
|-<br />
| isDefaultAccount || Boolean || Whether this account is the users default account. Exactly one account will have this flag set to <code>true</code>.<br />
|-<br />
| configuration || Object || Configuration data according to the formDescription of the relevant file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the relative (in context of the according file storage service) identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20547HTTP API2015-09-22T14:30:42Z<p>Steffen.templin: /* Update a folder */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 318 || account_id || String || Will be <code>null</code> if the folder does not belong to any account<br />
(i.e. if its module doesn't support multiple accounts), is a virtual folder or an account-agnostic system folder. Since 7.8.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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders for all modules except mail. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
=== 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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password or 'null' if the password wasn't set before (especially for guest users)<br />
|-<br />
| new_password || String || The new password the user wants to set or 'null' to remove the password (especially for guest users)<br />
|-<br />
|}<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account in the scope of its file storage service (Infostore, Dropbox.com, Google OneDrive etc.). This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage service this account belongs to <br />
|-<br />
| qualifiedId || String || Identifies a given file storage account globally, i.e. accross all file storage services. This is not writeable and is generated by the server <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 />
| rootFolder || String || ID of the accounts root folder within the folder tree. This is not writeable and is generated by the server <br />
|-<br />
| isDefaultAccount || Boolean || Whether this account is the users default account. Exactly one account will have this flag set to <code>true</code>.<br />
|-<br />
| configuration || Object || Configuration data according to the formDescription of the relevant file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the relative (in context of the according file storage service) identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20341HTTP API2015-09-07T14:27:50Z<p>Steffen.templin: /* File Storage Accounts */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 318 || account_id || String || Will be <code>null</code> if the folder does not belong to any account<br />
(i.e. if its module doesn't support multiple accounts), is a virtual folder or an account-agnostic system folder. Since 7.8.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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
=== 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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account in the scope of its file storage service (Infostore, Dropbox.com, Google OneDrive etc.). This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage service this account belongs to <br />
|-<br />
| qualifiedId || String || Identifies a given file storage account globally, i.e. accross all file storage services. This is not writeable and is generated by the server <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 />
| rootFolder || String || ID of the accounts root folder within the folder tree. This is not writeable and is generated by the server <br />
|-<br />
| isDefaultAccount || Boolean || Whether this account is the users default account. Exactly one account will have this flag set to <code>true</code>.<br />
|-<br />
| configuration || Object || Configuration data according to the formDescription of the relevant file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the relative (in context of the according file storage service) identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20340HTTP API2015-09-07T14:25:52Z<p>Steffen.templin: /* Get root folders */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 318 || account_id || String || Will be <code>null</code> if the folder does not belong to any account<br />
(i.e. if its module doesn't support multiple accounts), is a virtual folder or an account-agnostic system folder. Since 7.8.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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
=== 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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account in the scope of its file storage service (Infostore, Dropbox.com, Google OneDrive etc.). This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage service this account belongs to <br />
|-<br />
| qualifiedId || String || Identifies a given file storage account globally, i.e. accross all file storage services. This is not writeable and is generated by the server <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 />
| rootFolder || String || ID of the accounts root folder within the folder tree. This is not writeable and is generated by the server <br />
|-<br />
| configuration || Object || Configuration data according to the formDescription of the relevant file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the relative (in context of the according file storage service) identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20332HTTP API2015-09-03T10:02:21Z<p>Steffen.templin: /* File Storage Accounts */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
=== 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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account in the scope of its file storage service (Infostore, Dropbox.com, Google OneDrive etc.). This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage service this account belongs to <br />
|-<br />
| qualifiedId || String || Identifies a given file storage account globally, i.e. accross all file storage services. This is not writeable and is generated by the server <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 />
| rootFolder || String || ID of the accounts root folder within the folder tree. This is not writeable and is generated by the server <br />
|-<br />
| configuration || Object || Configuration data according to the formDescription of the relevant file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the relative (in context of the according file storage service) identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20331HTTP API2015-09-03T09:55:41Z<p>Steffen.templin: /* Active Facets */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
=== 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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20299HTTP API2015-09-01T15:29:00Z<p>Steffen.templin: /* Active Facets */</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 />
| 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 />
Because of security reasons each login variation will reject requests containing the parameter "password" within the URL query (starting with 7.8.0).<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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
GET <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", "infostore")<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 />
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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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. That parameter may be absent in case <code>ignore</code> is set to "deleted", which means all accessible calendar folders are considered. If <code>ignore</code> is not set to "deleted", that parameter is mandatory.<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> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<br />
* <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.<br>This parameter is optional in case a certain folder is queried, but mandatory if all accessible calendar folders are supposed to be considered (<code>folder</code> not specified)<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|-<br />
| 7020 || com.openexchange.realtime.resourceID || String || The resource identifier for the infoitem for usage within the realtime component. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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 />
===== Unsupported Facets (v7.8.0) =====<br />
As long as the client only adds facets that have been proposed by the most recent autocomplete response, it should never reach a state where invalid facet combinations are sent within query requests. However there is one exception: The facet "folder" is a virtual one which is composed by the client. A folder always belongs to a module and possibly belongs to one of several accounts within that module. Different accounts of one and the same module may differ in their search capabilities, which in turn leads to a different set of possible facets. If the client decides to change the folder facet, it must request another autocomplete including all active facets and the modified/added folder facet, with the prefix being the empty string. The response may contain an array of active facets for key "unsupported", which contains all facets that are no longer supported by the account behind the selected folder. The client must then remove those active facets before it sends the next query request. The objects within the "unsupported" are plain copies of the incoming objects. A client can rely on facet ID and value ID to find the ones to remove.<br />
<br />
<br />
====== Example ======<br />
The user is searching for term &quot;holiday&quot; globally in his personal folder &quot;My files&quot; with date in &quot;last week&quot;. He then switches the folder from &quot;My files&quot; to &quot;My Dropbox account&quot;, which results in another auto-complete roundtrip. The formerly selected date facet is not supported by the Dropbox account and needs to be removed before the next query request is sent.<br />
<br />
<br />
''Request:''<br />
<br />
<code>PUT http://mail.example.com/appsuite/api/find?action=autocomplete&amp;session=2d426d38371643d0a10d77b197c846aa&amp;module=drive</code><br />
<br />
<pre>{ <br />
&quot;prefix&quot;:&quot;&quot;,<br />
&quot;options&quot;:{ <br />
&quot;timezone&quot;:&quot;UTC&quot;,<br />
&quot;admin&quot;:false<br />
},<br />
&quot;facets&quot;:[ <br />
{ <br />
&quot;facet&quot;:&quot;global&quot;,<br />
&quot;value&quot;:&quot;global:holiday&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;global&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;holiday&quot;<br />
]<br />
}<br />
},<br />
{ <br />
&quot;facet&quot;:&quot;folder&quot;,<br />
&quot;value&quot;:&quot;dropbox://1/&quot;,<br />
&quot;filter&quot;:null<br />
},<br />
{ <br />
&quot;facet&quot;:&quot;date&quot;,<br />
&quot;value&quot;:&quot;last_week&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;date&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;last_week&quot;<br />
]<br />
}<br />
}<br />
]<br />
}</pre><br />
<br />
<br />
''Response:''<br />
<br />
<pre>{ <br />
&quot;data&quot;:{ <br />
&quot;facets&quot;:[ <br />
{ <br />
&quot;id&quot;:&quot;file_type&quot;,<br />
&quot;style&quot;:&quot;exclusive&quot;,<br />
&quot;name&quot;:&quot;File type&quot;,<br />
&quot;options&quot;:[ <br />
{ <br />
&quot;id&quot;:&quot;audio&quot;,<br />
&quot;name&quot;:&quot;Audio&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;file_mimetype&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;audio&quot;<br />
]<br />
}<br />
},<br />
{ <br />
&quot;id&quot;:&quot;text&quot;,<br />
&quot;name&quot;:&quot;Documents&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;file_mimetype&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;text&quot;<br />
]<br />
}<br />
},<br />
{ <br />
&quot;id&quot;:&quot;image&quot;,<br />
&quot;name&quot;:&quot;Images&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;file_mimetype&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;image&quot;<br />
]<br />
}<br />
},<br />
{ <br />
&quot;id&quot;:&quot;other&quot;,<br />
&quot;name&quot;:&quot;Other&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;file_mimetype&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;other&quot;<br />
]<br />
}<br />
},<br />
{ <br />
&quot;id&quot;:&quot;video&quot;,<br />
&quot;name&quot;:&quot;Video&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;file_mimetype&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;video&quot;<br />
]<br />
}<br />
}<br />
],<br />
&quot;flags&quot;:[ <br />
<br />
]<br />
}<br />
],<br />
&quot;unsupported&quot;:[ <br />
{ <br />
&quot;facet&quot;:&quot;date&quot;,<br />
&quot;value&quot;:&quot;last_week&quot;,<br />
&quot;filter&quot;:{ <br />
&quot;fields&quot;:[ <br />
&quot;date&quot;<br />
],<br />
&quot;queries&quot;:[ <br />
&quot;last_week&quot;<br />
]<br />
}<br />
}<br />
]<br />
}<br />
}</pre><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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20167HTTP API2015-08-05T13:41:35Z<p>Steffen.templin: /* Get all mails */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| || cid || String || The value of the "Content-ID" header, if the header is present.<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20120HTTP API2015-08-04T12:47:36Z<p>Steffen.templin: /* Create an infoitem via POST */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20119HTTP API2015-08-04T12:47:04Z<p>Steffen.templin: /* Create an infoitem via PUT */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20118HTTP API2015-08-04T12:46:06Z<p>Steffen.templin: /* Update an infoitem via POST */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. Sending out notifications for changed object permissions is possible, see the according PUT action for details on the request object.<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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20117HTTP API2015-08-04T12:44:23Z<p>Steffen.templin: /* Save an attachment in the infostore */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20116HTTP API2015-08-04T12:43:19Z<p>Steffen.templin: /* Update an infoitem via PUT */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared files. In that case you need to provide the file data as an object "file" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20115HTTP API2015-08-04T12:41:43Z<p>Steffen.templin: /* Update an infoitem via PUT */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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. It is possible to let added object permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"file":{<br />
"object_permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":1<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20113HTTP API2015-08-04T12:36:22Z<p>Steffen.templin: /* Create a folder */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templinhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20112HTTP API2015-08-04T12:35:29Z<p>Steffen.templin: /* Update a folder */</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 />
| 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 />
* <code>jsonResponse</code> (optional, since 7.8.0) – true or false (default). Defines the returned data type as JSON. Default 'false' will return a redirect. <br />
<br />
<br />
Response: A redirect to the web UI (or JSON including the redirect url in case jsonResponse=true is set). 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 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>pictures</code> – identifier of the default infostore pictures folder (read-only, since 7.8.0)<br />
***** <code>documents</code> – identifier of the default infostore documents folder (read-only, since 7.8.0)<br />
***** <code>music</code> – identifier of the default infostore music folder (read-only, since 7.8.0)<br />
***** <code>videos</code> – identifier of the default infostore videos folder (read-only, since 7.8.0)<br />
***** <code>templates</code> – identifier of the default infostore templates folder (read-only, since 7.8.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 />
<br />
=== Get a property (since 7.6.2) ===<br />
<br />
GET <code>/ajax/config?action=get_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to return.<br />
<br />
Response: A JSON response providing the property's name and its value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1234"<br />
}<br />
}<br />
</code><br />
<br />
=== Set a property (since 7.6.2) ===<br />
<br />
Note: Only allowed for context administrator!<br />
<br />
PUT <code>/ajax/config?action=set_property</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – The name of the property to set.<br />
<br />
Request body: A JSON object providing the value to set; e.g<br />
<code><br />
{"value":"test1237"}<br />
</code><br />
<br />
<br />
Response: A JSON response providing the property's name and its new value; e.g.<br />
<code><br />
{<br />
"data": {<br />
"name": "com.openexchange.dummy.prop001",<br />
"value": "test1237"<br />
}<br />
}<br />
</code><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 />
| 7 || This type is no more in use (legacy type). Will be removed with a future update!<br />
|-<br />
| 16 || trash<br />
|-<br />
| 20 || pictures<br />
|-<br />
| 21 || documents<br />
|-<br />
| 22 || music<br />
|-<br />
| 23 || videos<br />
|-<br />
| 24 || templates<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 mailing system capabilites, as described in [[#Capabilities | capabilities]].<br />
|-<br />
| 314 || subscribed || Boolean || Indicates whether this folder should appear in folder tree or not. '''Note:''' Standard folders cannot be unsubscribed.<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 />
| 3060 || com.openexchange.share.extendedPermissions || Array || Each element is an object described in [[#ExtendedPermissionObject | Extended permission object]]. Read Only, Since 7.8.0.<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 (ignored for type "anonymous" or "guest").<br />
|-<br />
| group || Boolean || true if entity refers to a group, false if it refers to a user (ignored for type "anonymous" or "guest").<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#PermissionFlags | Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<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 />
'''Note''': Capabilities describe the entire mailing system (mail account), not the specific folder in which they are transmitted. E.g. bit 4 of the capabilities on the user's inbox describes whether subscriptions are supported by the default account, even though the inbox itself cannot be unsubscribed because it's a standard folder.<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 />
* <code>cascadePermissions</code> – (Optional. Defaults to false) Flag to cascade permissions to all sub-folders. The user must have administrative permissions to all sub-folders subject to change. If one permission change fails, the entire operation fails. (Since 7.8.0)<br />
<br />
Request body: Folder object as described in [[#CommonFolderData | Common folder data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present. It is possible to let added permission entities be notified about newly shared folders. In that case you need to provide the folder data as an object "folder" and add a "notification" object beside it:<br />
<br />
<pre><br />
{<br />
"folder":{<br />
"permissions":[<br />
{<br />
"bits":403710016,<br />
"entity":84,<br />
"group":false<br />
},<br />
{<br />
"type":"guest",<br />
"email_address":"john.doe@example.com",<br />
"display_name":"John Doe",<br />
"bits":257<br />
}<br />
]<br />
},<br />
"notification":{<br />
"transport":"mail",<br />
"message":"Hi!\nHave a look at this!"<br />
}<br />
}<br />
</pre><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> – The optional 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 />
=== Get shared folders (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/folders?action=shares</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>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>content_type</code> – The desired content type (either numbers or strings; e.g. \"tasks\", \"calendar\", \"contacts\", \"infostore\"). Note: this action is not implemented for module "mail".<br />
<br />
Response with timestamp: An array with data for all folders that are considered as shared by the user. 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 />
=== Notify about shared folder (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/folders?action=notify</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>id</code> – Object ID of the shared folder to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
| 316 || start_time || Date or Time || Inclusive start as Date for whole day tasks and Time for normal tasks. <br />
|-<br />
| 317 || 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 || Marital 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 || Anniversary || 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 user id || user_id || 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 assistant || 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 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 <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 />
* <code>left_hand_limit</code> (optional) – A positive integer number to specify the "left-hand" limit of the range to return.<br />
* <code>right_hand_limit</code> (optional) – A positive integer number to specify the "right-hand" limit of the range to return.<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 />
| 128 || spam<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 />
| 108 || object_permissions || Array || Each element is an object described in [[#ObjectPermissionObject | Object Permission object]] (preliminary, available with 7.8.0).<br />
|-<br />
| 109 || shareable || Boolean || (read-only) Indicates if the item can be shared (preliminary, available with 7.8.0).<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 />
| 7010 || com.openexchange.share.extendedObjectPermissions || Array || Each element is an object described in [[#ExtendedObjectPermissionObject | Extended object permission object]]. Read Only, Since 7.8.0.<br />
|}<br />
<br />
{| id="ObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission object<br />
! Name !! Type !! Value<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<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 />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous" (required if no internal "entity" defined).<br />
|-<br />
| password || String || An additional secret / pin number an anonymous user needs to enter when accessing the share (for type "anonymous", optional) .<br />
|-<br />
| email_address || String || The e-mail address of the recipient (for type "guest").<br />
|-<br />
| display_name || String || The display name of the recipient (for type "guest", optional).<br />
|-<br />
| contact_id || String || The object identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", optional).<br />
|-<br />
| contact_folder || String || The folder identifier of the corresponding contact entry if the recipient was chosen from the address book (for type "guest", required if "contact_id" is set).<br />
|-<br />
| expiry_date || Time || The end date / expiration time after which the share link is no longer accessible (for type "anonymous", optional).<br />
|}<br />
<br />
{| id="ExtendedObjectPermissionObject" cellspacing="0" border="1"<br />
|+ align="bottom" | Extended object permission object<br />
! Name !! Type !! Value<br />
|-<br />
| entity || Number || Identifier of the permission entity (i.e. user-, group- or guest-ID).<br />
|-<br />
| bits || Number || A number as described in [[#ObjectPermissionFlags | Object Permission flags]].<br />
|-<br />
| type || String || "user" for an internal user, "group" for a group, "guest" for a guest, or "anonymous" for an anonymous permission entity.<br />
|-<br />
| display_name || String || A display name for the permission entity.<br />
|-<br />
| contact || Object || A (reduced) set of [[#DetailedContactData | Detailed contact data]] for "user" and "guest" entities.<br />
|-<br />
| share_url || String || The share link for "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry_date || Date || The optionally set expiry date for "anonymous" entities.<br />
|}<br />
<br />
{| id="ObjectPermissionFlags" cellspacing="0" border="1"<br />
|+ align="bottom" | Object Permission flags<br />
! Bits !! Value<br />
|-<br />
| 0 || The numerical value indicating no object permissions.<br />
|-<br />
| 1 || The numerical value indicating read object permissions.<br />
|-<br />
| 2 || The numerical value indicating write object permissions. This implicitly includes the “read” permission (this is no bitmask).<br />
|-<br />
| 4 || The numerical value indicating delete object permissions. This implicitly includes the “read” and “write” permission (this is no bitmask).<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=zipfolder</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 />
=== Get shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=shares</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 />
* <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 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 />
=== Notify about shared infoitems (Since 7.8.0, Preliminary) ===<br />
<br />
PUT <code>/ajax/infostore?action=notify</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 shared infoitem to notify about.<br />
<br />
Request body: A JSON object providing the JSON array <code>entities</code>, which holds the entity ID(s) of the users or groups that should be notified. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
* <code>charset</code> (preliminary, since 7.6.2) – Optional. A fixed character encoding to use when parsing the uploaded file, overriding the built-in defaults, following the conventions documented in RFC 2278.<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 />
<br />
==== Managed Image File ====<br />
GET <code>/image/mfile/picture</code> <br />
<br />
Parameters:<br />
* <code>uid</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 />
| 616 || Guest Created By || guest_created_by || Number || The ID of the user who has created this guest in case this user represents a guest user; it is 0 for regular users (preliminary, available with v7.8.0)<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 "user/me" (available with v7.6.2) ==<br />
<br />
The user/me module is used to access formal information about current user.<br />
<br />
=== Get user information ===<br />
<br />
GET <code>/ajax/user/me</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response with timestamp: A JSON object providing information for current user<br />
<br />
<code><br />
{<br />
"data": {<br />
"context_id": 1234,<br />
"user_id": 5,<br />
"is_context_admin": false,<br />
"login_name": "user5",<br />
"display_name": "User Five"<br />
},<br />
"timestamp": 1400855683800<br />
}<br />
</code><br />
<br />
== Module "OAuth" ==<br />
<br />
The Open-Xchange server can act as an OAuth client (starting with v6.20) or be an OAuth provider itself (starting with v7.8.0). The OAuth module supports both aspects:<br />
<br />
* Manage multiple OAuth accounts for certain 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. The according interface is divided into two parts: Account access and service's meta data access.<br />
* Manage granted accesses of external services that can access a users data on his behalf, called "grants".<br />
<br />
=== OAuth account access (available with v6.20) ===<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 (available with v6.20) ===<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 />
=== Manage OAuth grants (available with v7.8.0) ===<br />
<br />
==== Get all grants ====<br />
<br />
GET <code>/ajax/oauth/grants?action=all</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Response: A JSON array containing one object for every granted access as specified in [[#OAuthGrants | OAuth grants]].<br />
<br />
{| id="OAuthGrants" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth grants<br />
! Field !! Type !! Description<br />
|-<br />
| client || Object || A JSON object describing the external service as in [[#OAuthClient | OAuth client]].<br />
|-<br />
| scopes || Object || A JSON object with mappings from scope tokens to translated, human-readable descriptions for every scope that was granted to the external service. Example: {"read_contacts":"See all your contacts."}<br />
|-<br />
| date || Time || The time when the access was granted.<br />
|-<br />
|}<br />
<br />
{| id="OAuthClient" cellspacing="0" border="1"<br />
|+ align="bottom" | OAuth client<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || The clients ID.<br />
|-<br />
| name || String || The clients/services name.<br />
|-<br />
| description || String || A description of the client.<br />
|-<br />
| website || String || A URL to the clients website.<br />
|-<br />
| icon || String || A URL or path to obtain the clients icon via the "image" module.<br />
|-<br />
|}<br />
<br />
==== Revoke access ====<br />
<br />
GET <code>oauth/grants?action=revoke</code><br />
<br />
Parameters:<br />
* <code>client</code> - The ID of the client whose access shall be revoked.<br />
<br />
Response: Nothing.<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 />
=== General assumptions ===<br />
Some of the objects returned by the server contain former user input. A client must never interpret strings as HTML but always as plain text to be not vulnerable for CSS attacks!<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>.<br />
<br />
<br />
== Module "share/management" (preliminary, available with v7.8.0) ==<br />
<br />
Share links and can be created and managed via different actions in the "share/management" module. Additionally, there are dedicated actions to list all shares of a user in the modules [[#Get_shared_folders_.28Since_7.8.0.2C_Preliminary.29|"folders"]] and [[#Get_shared_infoitems_.28Since_7.8.0.2C_Preliminary.29|"files"]].<br />
<br />
=== Get a link ===<br />
<br />
PUT <code>/ajax/share/management?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: Basic information about an already existing or newly created share link as described in [[#ShareLink|Share Link]].<br />
<br />
{| id="ShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| module || String || The folder's module name, i.e. one of "tasks", "calendar", "contacts", "infostore" <br />
|-<br />
| folder || String || The folder identifier <br />
|-<br />
| item || String || (Optional) The object identifier, in case the share targets a single item <br />
|}<br />
<br />
{| id="ShareLink" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Link<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share (read-only)<br />
|-<br />
| entity || Number || The identifier of the anonymous user entity for the share (read-only)<br />
|-<br />
| is_new || Boolean || Whether the share link is new, i.e. it has been created by the <tt>getLink</tt>-request, or if it already existed (read-only)<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| meta || JSON || (Optional) Arbitrary JSON data saved along with the share as specified by client <br />
|}<br />
<br />
=== Update a link ===<br />
<br />
PUT <code>/ajax/share/management?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>timestamp</code> – The last modified timestamp of the link to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object as described in [[#ShareLink|Share Link]] containing the properties of the link to update., as well as the share target itself as described in [[#ShareTarget|Share Target]]. Only modified fields should be set.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Delete a link ===<br />
<br />
PUT <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be deleted for as described in [[#ShareTarget|Share Target]].<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Send a link ===<br />
<br />
PUT <code>/ajax/share/management?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: The share target where the link should be generated for as described in [[#ShareTarget|Share Target]]. The recipients are listed in the JSON array named <code>recipients</code>. Each element of the array is itself a two-element JSON array specifying one recipient. 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. To send a custom message to the recipients, an additional JSON object <code>notification</code> may be included, inside of which an optional message can be passed (otherwise, some default message is used).<br />
<br />
Response: An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the warnings array of the response.<br />
<br />
== Module "drive" ==<br />
The module <code>drive</code> is used to synchronize files and folders between server and client, using a server-centric approach to allow an easy implementation on the client-side. <br />
<br />
A detailed description can be found in a sepearet article: [[OX_Drive_API|OX Drive API]].<br />
<br />
<br />
== Module "passwordchange" ==<br />
<br />
Users can change their password via the "passwordchange" module. <br />
<br />
=== Update password ===<br />
<br />
Note: The new password will be set without any checks. The client must ensure that it is the password the user wants to set. <br />
<br />
PUT <code>/ajax/passwordchange?action=update</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object as described in PasswordChange.<br />
<br />
Response: An empty JSON result in case of no errors.<br />
<br />
{| id="PasswordChange" cellspacing="0" border="1"<br />
|+ align="bottom" | Password change<br />
! Name !! Type !! Value<br />
|-<br />
| old_password || String || The users' current password<br />
|-<br />
| new_password || String || The new password the user wants to set<br />
|-<br />
|}<br />
<br />
<br />
== File Storage Services ==<br />
<br />
File storage services represents a file storage backend; e.g. Drive, Dropbox, etc.<br />
<br />
A *File Storage Service* Object has the following structure:<br />
<br />
{| id="FileStorageService" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Service<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a file storage service. Example: "boxcom"<br />
|-<br />
| displayName || String || Human readable display name of the service. Example: "Box File Storage Service" <br />
|-<br />
| configuration || JSON object || A description for dynamic form fields. Same as in PubSub <br />
|-<br />
|}<br />
<br />
The available JSON calls are:<br />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileservice?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 file storage service objects. <br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileservice?action=get<br />
<br />
* session - A session ID previously obtained from the login module. <br />
* id - The ID of the file storage service to load<br />
<br />
Response: A standard response object containing a file storage service object.<br />
<br />
== File Storage Accounts ==<br />
<br />
A file storage account represents the concrete configuration of an account of a given file storage service.<br />
A *file storage account* has the following structure:<br />
<br />
{| id="FileStorageAccount" cellspacing="0" border="1"<br />
|+ align="bottom" | File Storage Account<br />
! Field !! Type !! Description<br />
|-<br />
| id || String || Identifies a given file storage account. This is not writeable and is generated by the server <br />
|-<br />
| filestorageService || String || The identifier of the file storage 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 file storage service <br />
|-<br />
|}<br />
<br />
The available JSON calls are<br />
<br />
=== Create a file storage account ===<br />
PUT /ajax/fileaccount?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 />
=== Update a file storage account ===<br />
PUT /ajax/fileaccount?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 "filestorageService" must always be set.<br />
Response: A response object containing the number 1 as its data on success.<br />
<br />
<br />
=== Get a file storage account ===<br />
GET /ajax/fileaccount?action=get<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Delete a file storage account ===<br />
GET /ajax/fileaccount?action=delete<br />
<br />
* session - A session ID previously obtained from the login module.<br />
* filestorageService - The file storage 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 />
<br />
=== Get all available file storage accounts ===<br />
GET /ajax/fileaccount?action=all<br />
<br />
* session - A session ID previously obtained from the login module<br />
* filestorageService - (optional) list only those accounts that belong to the given file storage service.<br />
<br />
Response: A response object containing a JSON array of account objects in its data section.<br />
<br />
<br />
=== Example for creating a new OAuth-based file storage account ===<br />
<br />
First, get the description of the file storage service for which a new account is supposed to be created:<br><br />
<code>GET /ajax/fileservice?action=get&id=boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{<br />
id: "boxcom"<br />
displayName: "Box File Storage Service"<br />
configuration: {<br />
widget: "oauthAccount"<br />
options: {<br />
type: "com.openexchange.oauth.boxcom"<br />
}<br />
name: "account"<br />
displayName: "Select an existing account"<br />
mandatory: true<br />
}<br />
}<br />
</code><br />
<br />
Next get the associated OAuth account information:<br><br />
<code>GET /ajax/oauth/accounts?action=all&serviceId=com.openexchange.oauth.boxcom&session=...</code><br />
<br />
The response might be:<br />
<code><br />
{"data":[{"id":333,"displayName":"My Box.com account","serviceId":"com.openexchange.oauth.boxcom"}]}<br />
</code><br />
<br />
Finally, create the file storage account:<br><br />
<code><br />
PUT /ajax/fileaccount?action=new&session=...<br />
<br />
{<br />
"filestorageService":"boxcom",<br />
"displayName":"My box.com account",<br />
"configuration":{<br />
"account":"333",<br />
"type":"com.openexchange.oauth.boxcom"<br />
}<br />
}<br />
</code><br />
<br />
The response provides the identifier of the newly created account:<br />
<code>{"data":19}</code></div>Steffen.templin