https://oxpedia.org/wiki/api.php?action=feedcontributions&user=Martin.schneider&feedformat=atomOpen-Xchange - User contributions [en]2024-03-28T10:51:30ZUser contributionsMediaWiki 1.31.0https://oxpedia.org/wiki/index.php?title=CardDAVClients&diff=25300CardDAVClients2020-04-09T12:53:43Z<p>Martin.schneider: </p>
<hr />
<div>This article is valid until the version 7.10.2 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/develop/middleware/miscellaneous/caldav_carddav/carddav_clients.html<br />
<br />
= Open-Xchange Contacts synchronization with CardDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CardDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Contacts ==<br />
<br />
For the Contacts application on Mac OS X 10.9 (Mavericks) and above, a CardDAV account can be configured as follows:<br />
<br />
{| <br />
| [[image:carddav-account5.png|thumb]] || style="width:85%" |<br />
* Click the "+" sign in Address Book -> Preferences -> Accounts.<br />
* In the "Account type" field keep "CardDAV" selected<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''usually with the prefix "dav." (e.g. "dav.myserver.tls")'''.<br />
* Click "Create"<br />
|}<br />
<br />
== iOS Contacts ==<br />
''Available since Open-Xchange Server v6.22''<br />
<br />
The iOS Contacts application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_carddav_config.png|thumb]] || style="width:85%" |<br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CardDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CardDAV interface:<br />
<br />
=== Unsupported Properties ===<br />
* Generally, only those contact properties that are also available on the Open-Xchange server are recognized and transferred into attributes of OX contacts<br />
* Starting with v7.8.0, the original vCard is also preserved, so that other extended or not mapped properties are still available there (see [[AppSuite:VCardMapping]] for details)<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CardDAV interface.<br />
* Due to various different handlings of representing distribution list members in vCards, distribution lists are excluded from syncrhonization via CardDAV.<br />
<br />
=== Unsupported Special Chars ===<br />
* The special char "/" in contact names is not supported. It will lead to an "HTTP/1.1 404 Not Found" error in webdav.<br />
<br />
=== Client Restrictions ===<br />
* The Mac Contacts App does not Support CalDAV Collections. Open-Xchange by default recognizes this and exposes an aggregated collection of the CalDAV Collections. As a consequence new contacts entered in subfolders on OX side will not appear in subfolders (or Contact Groups) on the Mac Contacts App but inside of the aggregated Collection itself. Additionally Contact Groups from the Contacts App are not synced to OX - however the Contacts itself will be synced to the OX Address Book. Creating a new Contacts Group from within the Contacts App using the OX CardDAV Account is not possible - the name will revert to “untitled group” and will not be synced to OX App Suite.</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=CalDAVClients&diff=25299CalDAVClients2020-04-09T12:52:56Z<p>Martin.schneider: </p>
<hr />
<div>This article is valid until the version 7.10.2 of the Open Xchange Server. For newer versions please visit https://documentation.open-xchange.com/develop/middleware/miscellaneous/caldav_carddav/caldav_clients.html<br />
<br />
= Open-Xchange Calendar synchronization with CalDAV =<br />
<br />
This site describes how the Open-Xchange server can be accessed via its CalDAV interface after the server has been configured as described in [[Caldav_carddav_Bundles]]. Depending on the used client software, different steps are necessary. Other clients may be configured similarly, but are not officially supported.<br />
<br />
== Mac OS X Calendar ==<br />
<br />
For the Calendar application on Mac OS X 10.9 (Mavericks) and above, a CalDAV account can be configured as follows:<br />
<br />
{| <br />
| [[image:caldav-account4.png|thumb]] || style="width:85%"| <br />
* Choose "Calendar" -> "Add Account..." from the Calendar App main Menu<br />
* In the "Choose Calendar Account Provider..." Menu choose "Other CalDAV-Account..."<br />
* In the "Add a CalDAV Account" Menu choose "Account Type" "Manual"<br />
* In the "User name" field enter your username<br />
* In the "Password" field enter your password<br />
* In the "Server address" field enter your server address '''with the prefix "dav." (e.g. "dav.myserver.tld")'''.<br />
* Click "Sign In"<br />
|}<br />
<br />
=== Debug Options ===<br />
You can enable a Debug Menu inside the iCal application which gives you access to advanced debugging and logging options. Please notice that some of these options may increase the size of the log files of your system and/or could also log sensitive data like passwords if enabled. Keep also in mind that any setting changed here will remain active until the setting itself will be reverted or changed again which means that disabling the Debug Menu itself is not sufficient to reset any debug settings to their defaults. All settings are case sensitive.<br />
<br />
Open a terminal window (Applications > Utilities > Terminal) and issue the following command for<br />
* enabling the Debug Menu in iCal:<br />
defaults write com.apple.iCal CDB 1<br />
* disabling the Debug Menu in iCal:<br />
defaults write com.apple.iCal CDB 0<br />
* enabling CalDAV HTTP activity logging:<br />
defaults write com.apple.iCal LogHTTPActivity -boolean TRUE<br />
* disabling CalDAV HTTP activity logging:<br />
defaults write com.apple.iCal LogHTTPActivity -boolean FALSE<br />
<br />
Starting with Mac OS 10.12 ("Sierra"), the log can be retrieved by the log utility from the commandline, e.g. via <br />
log stream --level=all --process CalendarAgent<br />
<br />
In previous versions, the logs are available in the "console" application.<br />
<br />
'''Pay attention''': If you change these settings it might be needed to kill the CalendarAgent process with <code>killall CalendarAgent</code> just restarting the MacOS calendar application might not be enough. So in case you won't see any additional log output in the syslog, or the additional log output doesn't vanish after switching off these setting, please try killing the CalendarAgent process.<br />
<br />
== iOS Calendar ==<br />
<br />
The iOS Calendar application on the iPhone, iPod or iPad can be configured as follows.<br />
<br />
{| <br />
| [[image:ios_caldav_config.png|thumb]] || style="width:85%"| <br />
* Open "Settings"<br />
* Select "Mail, Contacts, Calendars" -> "Add Account..." -> "Other" -> "Add CalDAV Account"<br />
* Enter the server address, username as password as shown in the screenshot<br />
* Click "Next"<br />
|}<br />
<br />
== Thunderbird/Lightning ==<br />
''Available since Open-Xchange Server v6.20.7''<br />
<br />
The steps below describe how to setup the Mozilla Thunderbird client with the Lightning Add-on. <br />
<br />
=== Prerequisites ===<br />
Please ensure that the following preconditions are met before continuing:<br />
* Latest versions of the Mozilla Thunderbird E-Mail client and the Lightning Add-on (check https://addons.mozilla.org/thunderbird/addon/lightning/ and http://www.mozilla.org/thunderbird/ for details)<br />
* In the Mozilla Thunderbird client, an E-Mail account for the user's Open-Xchange mailbox needs to be setup before configuring the CalDAV access<br />
<br />
=== Discover the CalDAV URL of your Calendar Folders ===<br />
In contrast to some other clients, Thunderbird/Lightning is not able to discover all the available calendar collections automatically. Instead, each calendar folder needs to be added seperately in the client. To do so, one needs to know the CalDAV URLs of the calendar folder that should be synchronized with the client. This URL is displayed in the properties-page in the Groupware web-interface.<br />
<br />
{| <br />
| [[image:CalDAV_URL_Step1.png|thumb]] || style="width:85%"| <br />
* Open a webbrowser and login to the groupware web-interface<br />
* From the folder tree, open the context menu of a calendar folder and select "Properties"<br />
|-<br />
| [[image:CalDAV_URL_Step2.png|thumb]] ||<br />
* The CalDAV URL is shown in the content area. Note down the URL or copy it to the clipboard.<br />
|}<br />
<br />
=== Add a Calendar in Thunderbird/Lightning ===<br />
As already mentioned, each Calendar folder that should be sychronized has to be added separately in the client. The following steps show how to add a Calendar in Thunderbird/Lightning. Before starting, ensure that the client is connected to the network and the server can be accessed.<br />
<br />
{| <br />
| [[image:LightningSetup_Step1.png|thumb]] || style="width:85%"| <br />
* Select "Events and Tasks" -> "Calendar" from the menu bar to switch to the Calendar view<br />
|-<br />
| [[image:LightningSetup_Step2.png|thumb]] || style="width:85%"| <br />
* From the menu bar, select "File" -> "New" -> "Calendar..."<br />
|-<br />
| [[image:LightningSetup_Step3.png|thumb]] || style="width:85%"| <br />
* In the popup window, select "On the network" and click "Next >"<br />
|-<br />
| [[image:LightningSetup_Step4.png|thumb]] || style="width:85%"| <br />
* As format, select "CalDAV"<br />
* Enter the CalDAV path as reported by the folder's properties page (see above) as location<br />
* For offline access, check the "Cache" checkbox <br />
* Click "Next >" to continue<br />
|-<br />
| [[image:LightningSetup_Step5.png|thumb]] || style="width:85%"| <br />
* Enter a name for the Calendar and assign a color if you like <br />
* Select whether reminders should be shown or not (recommended setting: off, see below for details)<br />
* Select the E-Mail account belonging to the Calendar user from the list <br />
* Click "Next >" to create the Calendar <br />
|-<br />
| [[image:LightningSetup_Step6.png|thumb]] || style="width:85%"| <br />
* When requested, enter your username and password for the server<br />
* Afterwards, the Calendar setup is complete and the contents are synchronized<br />
|}<br />
<br />
=== Debug Options ===<br />
In case of synchronization problems, the built-in error console of Mozilla Thunderbird may provide valuable information. The error console can be opened via "Tools" -> "Error Console". To increase the loglevel of the Lightning Add-on, open the config editor by selecting "Tools" -> "Options..." -> "Advanced" -> "Config Editor..." and set the properties "calendar.debug.log" and "calendar.debug.log.verbose" to "true".<br />
<br />
<br />
== General Limitations ==<br />
Please consider the following known limitations for the CalDAV interface:<br />
<br />
=== Reminders ===<br />
* While the iCalendar standard allows to set appointment reminders past due an appointment's start-date, the OX server is not able to save such alarm times and discards them.<br />
* Multiple reminders in an event are not supported by the OX server and are discarded.<br />
* Only reminders of type "DISPLAY" are supported by the OX server, reminders of other iCal types are discarded.<br />
* When dismissing reminders of recurring appointments in the Mozilla Lightning client, the reminder is removed from the whole recurring appointment object, since it's not possible to determine to which occurrence the dismiss action belongs to.<br />
* On iOS devices, when a custom default alert time is configured via Settings -> Mail, Contacts, Calendars -> Default Alert Times, this setting may also affect appointments you don't participate in. This is a client-specific feature and can't be influenced by the server.<br />
* Due to incompatible handling of reminders in the Mozilla Thunderbird / Lightning client, especially for reminders in recurring appointments, it's recommended to turn off reminders in synchronized calendar folders there (from the context menu of a calendar, select 'Properties' and uncheck 'Show Alarms').<br />
<br />
=== Attachments ===<br />
<br />
Since v7.8.1, the OX server has support for synchronizing appointment attachments via CalDAV. Attachments are included as so-called managed attachments in the iCal data, which are basically ATTACH properties whose value is a link to the attachment's binary data on the server. More details are available at https://datatracker.ietf.org/doc/draft-daboo-caldav-attachments/ .<br />
<br />
Depending on the used client, some specials apply:<br />
<br />
==== Mac OS Calendar ====<br />
* For appointments with existing attachments, the client sometimes refuses to apply local updates and displays a "Are you sure you want to delete the attachment" warning<br />
* Occasionally, the client crashes when working with appointments having attachments (due to an uncaught internal error)<br />
* In recurring appointments, there is no separation between the series itself and possible exceptions, i.e. the client displays a combined view of attachments for both the series itself, as well as those files that are attached to an exception instance<br />
* The same goes for all attachment-related operations in recurring events, i.e. attachments are added, updated and removed from the main series only, regardless of an exception being selected<br />
* To offer at least basic support for attachments, the server tries to mimic a CalDAV server not being able to support storing managed attachments on a per-recurrence instance basis (i.e., they can only be added to all instances as a whole), which correlates to the "calendar-managed-attachments-no-recurrence" capability)<br />
<br />
====eM Client==== <br />
* In recurring appointments, the client displays both the attachments of the main series, as well as those from the exception. However, not the other way around, i.e. attachments targeting the exception explicitly don't show up in the main series.<br />
* Besides displaying both attachments from the series as well as those from exception occurrences, the client also indicates all those attachments again when editing an exception again. Therefore, such attachments that already exist in the main series are skipped implicitly when importing the updated appointment again.<br />
<br />
<br />
=== Unsupported Properties ===<br />
* Generally, only those appointment and task properties that are also available on the Open-Xchange server are used for synchronization, i.e. all unsupported properties are ignored and not saved.<br />
* The "URL" property for iCal resources is not supported by the OX server and is discarded.<br />
* Importing or exporting file attachments (property "ATTACH") is not supported via the CalDAV interface prior v7.8.1.<br />
<br />
=== Private Appointments ===<br />
* Appointments classified as "private" are exported by the server with the "CLASS" property set to "PRIVATE".<br />
* iCal events with the "CLASS" property set to either "CONFIDENTIAL" or "PRIVATE" are treated in the same way by the server and are imported as "private" appointments.<br />
* Since "private" appointments with participants are not supported by the server, saving such an appointment results in the participants being removed implicitly during import.<br />
<br />
=== Tasks ===<br />
* Only simple tasks (no participants, no recurrence) are supported.<br />
* Only tasks from personal folders (no shared or public folders) are supported.<br />
* Only the properties "DTSTART", "DUE", "CATEGORIES", "SUMMARY", "PRIORITY", "DESCRIPTION", "VALARM", "STATUS", "PERCENT-COMPLETE" and "COMPLETED" are synchronized, other ones are discarded by the server.<br />
<br />
===Creating new Collections===<br />
* Creating a new collection in the client results in a new folder being created at the server, with the default calendar or tasks folder as its parent. <br />
* In the Mac OS clients, the name of a new folder may be need to set twice during creation, since the collection's location as chosen by the client changes once after sending it to the server. <br />
* Note: Due to the lacking support of the MKCALENDAR HTTP request in Apache's mod_ajp module, creating new collections currently only works when using the [[Grizzly]] package on the OX server.<br />
<br />
===Permissions in Shared Folders===<br />
* In a Calendar folder that is shared to the CalDAV user by another groupware user, the Mac OS iCal client does not allow editing appointments where the CalDAV user is not the organizer of the appointment, even if sufficient permissions were granted. This is a built-in restriction of the client, however, you are still able to edit or delete such appointments in the groupware web interface.</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:DBMigration&diff=24558AppSuite:DBMigration2019-03-14T10:03:12Z<p>Martin.schneider: /* Database tables */</p>
<hr />
<div><!-- Author: Martin Schneider <martin.schneider@open-xchange.com> --><br />
<br />
{{VersionFrom|7.6.1}}<br />
<br />
<div class="title">Database migration for Open-Xchange server.</div><br />
<br />
'''Summary''': With release 7.6.1 it is possible to change the database schema based on usage of the open source tool Liquibase. Currently this applies to the config database, as well as so-called global databases for storing cross-context data (available with v7.8). This article gives a short introduction about the current implementation.<br />
<br />
Please have a look at Liquibase, its features and documentation before working with database migrations for Open-Xchange server: http://www.liquibase.org/documentation/ and http://www.liquibase.org/bestpractices.html .<br />
<br />
Ho to create custom bundles is explained in an extra article: http://oxpedia.org/wiki/index.php?title=AppSuite:CustomDBMigration<br />
<br />
__TOC__<br />
<br />
== Database migration bundles ==<br />
The following bundles provide the functionality for executing database migration statements. All are included within the open-xchange-core package.<br />
<br />
* com.openexchange.database.migration: Provides the service to execute database migrations and the core database ChangeLogs<br />
* com.openexchange.database.migration.clt: Provides a command line tool that might help by working with database migrations based on Liquibase<br />
<br />
== Current restrictions ==<br />
* Open-Xchange server currently uses Liquibase version 3.0.7. All features provided with later versions cannot be used.<br />
<br />
== Liquibase ==<br />
The following chapter describes shortly the Liquibase features and how they are used by Open-Xchange. For further information have a look at the official Liquibase documentation: http://www.liquibase.org/documentation/<br />
<br />
=== ChangeLog file / changeSets ===<br />
A ChangeLog file is the heart of this database migration and contains all information required to change database structure and/or contents. It consists of ChangeSets that are used to define a migration. Normally ChangeSets are executed transactionally.<br />
<br />
=== Tags ===<br />
A ChangeSet can be used to tag the database at a current state. Open-Xchange uses this mechanism to tag the database to be ready for a new release. <br />
<br />
=== Database ===<br />
<br />
==== Database tables ====<br />
Liquibase creates two tables to handle its current state:<br />
<br />
* DATABASECHANGELOG: Contains information about the execution status of ChangeSets. Each executed ChangeSet will be added to this table. If there is no entry available for a ChangeSet Liquibase will try to execute the statement.<br />
* DATABASECHANGELOGLOCK: Handles access to the database to not execute database migration statements twice.<br />
<br />
==== Database lock ====<br />
<br />
Liquibase uses a lock to only grant one Liquibase instace access to the database to change. For this purpose a table named 'DATABASECHANGELOGLOCK' is created. In cluster environments the first node that successfully aquired the lock will execute the database migration statements. During this time all other nodes are blocked. After the lock was released the second node will get access to the database and read already executed ChangeSets. If all ChangeSets have been executed nothing will be done and the lock will be released. This happens with each node within the cluster.<br />
<br />
=== Custom Java Classes ===<br />
<br />
Implementing CustomSqlChange enables you to write custom SQL statements instead of using declarative statements. <br />
<br />
== Implementation details ==<br />
<br />
The Open-Xchange server will wait within the startup until all provided Liquibase update tasks have been executed to ensure consistent data usage!<br />
<br />
== Command line tool ==<br />
Currently a command line tools is provided to manage the migrations: ''/opt/open-xchange/sbin/dbmigrations'' (Note: in versions prior v7.8, the utitlity is named ''configdbmigrations'', and the ''name'' option is missing):<br />
<br />
usage: dbmigrations<br />
-A,--adminuser <arg> Admin username<br />
-h,--help Prints a help text<br />
-l,--login <arg> The optional JMX login (if JMX<br />
authentication is enabled)<br />
-ll,--list-locks Lists all currently acquired locks.<br />
-n,--name <arg> The database schema name to use<br />
-P,--adminpass <arg> Admin password<br />
-p,--port <arg> The optional JMX port (default:9999)<br />
-r,--run Forces a run of the current core changelog.<br />
--responsetimeout <arg> The optional response timeout in seconds<br />
when reading data from server (default: 0s;<br />
infinite)<br />
-s,--password <arg> The optional JMX password (if JMX<br />
authentication is enabled)<br />
-t,--host <arg> The optional JMX host (default:localhost)<br />
-u,--force-unlock Forces a release of all locks.<br />
Prints the current migration status if no option is set.<br />
<br />
== Important hints == <br />
* ChangeSets are executed top-down within a ChangeLog, so always add new migrations at the bottom of the file. For migrations regarding core components always use the configdbChangeLog.xml in com.openexchange.database.migration/resource/liquibase. For non-core components see [[AppSuite:CustomDBMigration]].<br />
* ChangeSets must be constructed in an idempotent manner, i.e. they must not fail or break something if they are run several times. Use preconditions with onFail="MARK_RAN" to achieve this.<br />
* If you are adding the first migration for an upcoming release, add an according milestone tag after the actual migration ChangeSets!<br />
* If you would like to use <include> statements to reference other files with Liquibase statements we suggest adding parameter 'relativeToChangelogFile="true"' to avoid adding complete paths.<br />
* http://www.liquibase.org/documentation/sql_output.html<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]<br />
[[Category: Database]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=23529HTTP API2017-07-05T09:40:23Z<p>Martin.schneider: Corrected 'valid until'</p>
<hr />
<div>{{Version_until|7.8.2}}<br />
<br />
'''The latest content on this page has moved to https://documentation.open-xchange.com/components/middleware/http/latest/index.html.'''<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 />
== 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 />
* for POST requests all described parameters are normally expected in the request body, exceptions are documented,<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 are normally expected in the POST request body:<br />
* <code>name</code> – The login name.<br />
* <code>password</code> – The password MUST be placed in the request body, otherwise the login request will be denied.<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 />
=== Autologin ===<br />
<br />
If the session ID was stored in a cookie before via the [[#Refresh_auto-login_cookie | store request]], the user can reuse his old session by using the autologin request.<br />
<br />
GET <code>/ajax/login?action=autologin</code><br />
<br />
Parameters:<br />
<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.<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 />
<br />
Response: A JSON object containing the session ID used for all subsequent requests.<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>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 "left-hand" limit of the range to return<br />
* <code>right_hand_limit</code> - A positive integer number to specify the "right-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 />
| 654 || original_id || String || The original mail identifier (e.g. if fetched from "virtual/all" folder).<br />
|-<br />
| 655 || original_folder_id || String || The original folder identifier (e.g. if fetched from "virtual/all" folder).<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 "left-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 "right-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 />
<br />
=== Search mails (alternative) ===<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 mails 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 object containing filters. <code>{"filter":<i>[search term]</i>}</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: "from" }</code>. The available field names are <code>from</code>, <code>to</code>, <code>cc</code>, <code>bcc</code>, <code>subject</code>, <code>received_date</code>, <code>sent_date</code>, <code>size</code>,<code>flags</code>, <code>content</code>, <code>content_type</code>, <code>disp</code> and <code>priority</code> as defined in [[#DetailedMailData | Detailed mail data]]. 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 />
<code><br />
{"filter":<br />
["or",<br />
["and",<br />
["=", {"field":"to"}, "test1@example.org"],<br />
["not",<br />
["=", {"field":"from"}, "test2@example.org"]<br />
],<br />
[">", {"field":"received_date"}, "1458063382000"]<br />
],<br />
["=", {"field":"subject"}, "TestSubject"]<br />
]<br />
}<br />
</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 />
=== 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 />
* <code>lineWrapAfter</code> – An integer value specifying the line-wrap setting (only effective for plain-text content); if absent the setting is taken from user's mail settings. Available with v7.8.1.<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>folder</code> (optional) – The folder ID to restrict the search to. If not specified, all folders are searched.<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: The search pattern string in a JSON object named "pattern".<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 />
=== Check if file name is valid (since 7.8.1, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=checkname</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – Name of the file to check.<br />
<br />
Response: An empty JSON object when file name is valid.<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>offset</code> – Optionally sets the start offset in bytes where to append the data to the document, must be equal to the actual document's length (available with v7.8.1). Only available if the underlying [[#FileStorageAccount | File storage account]] supports the "RANDOM_FILE_ACCESS" capability.<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 />
| 1044 || mail_starttls || Boolean || '''Available since v7.8.2''' Whether to establish a secure connection to mail server via STARTTLS.<br />
|-<br />
| 1045 || transport_starttls || Boolean || '''Available since v7.8.2''' Whether to establish a secure connection to transport server via STARTTLS.<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 />
POST <code>/ajax/autoconfig?action=get</code><br />
<br />
application/x-www-form-urlencoded 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 />
* <code>force_secure</code> – '''Available since v7.8.2''' Enforce a secure connection for configured mail account, default is true (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 />
| capabilities || List of Strings || A list of capability names. Possible values are: "FILE_VERSIONS", "EXTENDED_METADATA", "RANDOM_FILE_ACCESS", "LOCKS" <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>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=MailReportSpamhandler&diff=22887MailReportSpamhandler2017-02-14T10:47:17Z<p>Martin.schneider: MW-577: adapt documentation to new ConfigCascade possibility</p>
<hr />
<div>= Introduction =<br />
<br />
This OXpedia article describes, how to set up a spamhandler which optionally reports ham and spam via mail to any email address system with Open-Xchange.<br />
<br />
In addition it moves the mail to the spam folder if marked as spam and into the Inbox if a message in the spam folder is again marked as ham. The exact behaviour can be configured.<br />
<br />
To get the UI controls all users need to be provisioned accordingly. There is no global switch to enable/disable.<br />
<br />
<br />
= Prerequisites =<br />
<br />
== Target mail ==<br />
<br />
For setting up the spamhandler you require the address where to send ham and spam reports to.<br />
<br />
<br />
= Installation =<br />
<br />
We will need to install the following package on the Open-Xchange server.<br />
[Please note that even if the package carries the name cloudmark it is not bound to Cloudmark product. Though Cloudmark uses the same very generic reporting method.]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-spamhandler-cloudmark|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}<br />
<br />
= Configuration =<br />
<br />
Open the following file in editor<br />
<pre><br />
$ /opt/open-xchange/etc/imap.properties<br />
</pre><br />
<br />
Edit the following parameter to:<br />
<br />
<pre><br />
com.openexchange.imap.spamHandler=CloudmarkSpamHandler<br />
</pre><br />
<br />
Open the following file in editor<br />
<pre><br />
$ /opt/open-xchange/etc/spamhandler_cloudmark.properties<br />
</pre><br />
<br />
Edit the following parameters to configure the reporting service:<br />
<pre><br />
# Defines the eMail address to which the selected eMails will be bounced. If no<br />
# address is specified the bounce will be skipped, but moving the selected mails<br />
# to the target folder will still be processed (if configured)<br />
com.openexchange.spamhandler.cloudmark.targetSpamEmailAddress=<br />
<br />
# Defines the eMail address to which the selected eMails will be bounced, if they<br />
# are marked as Ham. If no address is specified the bounce will be skipped,<br />
# but moving the selected mails back to the Inbox will still be processed (if configured).<br />
# Privacy note: This will send private mails of users to that address when marked as Ham<br />
com.openexchange.spamhandler.cloudmark.targetHamEmailAddress=<br />
<br />
# Defines to which folder the selected mails should be moved to after they have<br />
# been bounced to the target eMail address. If no option is configured the<br />
# selected mails will be moved to the users trash folder. Possible options are:<br />
#<br />
# 0 = Do not move the message at all (not recommended)<br />
# 1 = User's trash folder (Default)<br />
# 2 = User's SPAM folder<br />
# 3 = Subscribed confirmed-spam folder (experimental)<br />
com.openexchange.spamhandler.cloudmark.targetSpamFolder=2<br />
<br />
# Defines if the spam/ham message is passed as a nested message to the target address<br />
#<br />
# ----------------------------------== /!\ ==----------------------------------------<br />
# Note: This option needs to be clarified with your running Cloudmark service that<br />
# passing the spam/ham message as a nested message is accepted and properly<br />
# handled!<br />
# -----------------------------------------------------------------------------------<br />
#<br />
# Default is "true"<br />
com.openexchange.spamhandler.cloudmark.wrapMessage=true<br />
</pre><br />
<br />
Once done then reboot the OX Service<br />
<pre><br />
$ service open-xchange restart<br />
</pre><br />
<br />
<br />
<br />
Finally, we will need to enable the capabilities for SPAM. To do this we have to run the following command for e.g.<br />
<br />
<pre><br />
$ changeuser -A oxadmin -P admin_password -c contextID -u username --gui_spam_filter_capabilities_enabled true <br />
</pre><br />
<br />
or to set the property <tt>com.openexchange.spamhandler.enabled</tt> to <tt>true</tt> via ConfigCascade<br />
<br />
[[Category: Administrator]]<br />
<br />
[[Category: AppSuite]]<br />
<br />
[[Category: Spamhandling]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Spamassassin&diff=22886Spamassassin2017-02-14T10:44:20Z<p>Martin.schneider: MW-577: adapt documentation to new ConfigCascade possibility</p>
<hr />
<div>= Introduction =<br />
<br />
This OXpedia article describes, how to connect the [http://spamassassin.apache.org/ SpamAssassin] system with Open-Xchange.<br />
It allows accessing your SpamAssassin settings from within Open-Xchange and use the spam- and ham<br />
Learning mechanisms of SpamAssassin directly from within the Open-Xchange UI.<br />
<br />
= Prerequisites =<br />
<br />
== Sieve ==<br />
<br />
You will need to install and configure the [http://sieve.info/ SIEVE] Mail filter program on your mail server. Since we will '''not''' cover the installation part of Sieve in this article, therefore we will only tell the important configuration settings needed for Sieve to get integrated with Open-Xchange.<br />
<br />
== SpamAssassin ==<br />
<br />
You will also need to install and configure the [http://spamassassin.apache.org/ SpamAssassin]. Since we will '''not''' cover the installation part of SpamAssassin in this article, therefore we will only tell the important configuration settings needed for SpamAssassin to get integrated with Open-Xchange.<br />
<br />
= Installation =<br />
<br />
We will need to install the following two packages on the Open-Xchange server.<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|sopath=6.22/backend|version=v6.22.x}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-spamhandler-spamassassin open-xchange-mailfilter|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}<br />
<br />
= Configuration =<br />
<br />
== For Sieve ==<br />
<br />
As we have now already installed the needed package '''open-xchange-mailfilter'''. Now we need to configure the setting the configuration file so that Open-Xchange can be integrated with Sieve.<br />
<br />
Open the following file in your Linux editor.<br />
<pre><br />
$ /opt/open-xchange/etc/mailfilter.properties<br />
</pre><br />
<br />
Edit the following lines<br />
<br />
<pre><br />
SIEVE_SERVER=localhost //your sieve server name, localhost is default for single machine<br />
<br />
SIEVE_PORT=4190 //this port should be same as the one you define during the installation of Sieve.<br />
</pre><br />
<br />
Save the changes and reboot Open-Xchange service.<br />
<br />
<pre><br />
$ /etc/init.d/open-xchange restart<br />
</pre><br />
<br />
Verify that the mailfilter bundle has started properly and should be ACTIVE.<br />
<pre><br />
$ listbundles | grep filter <br />
<br />
bundlename: com.openexchange.mail.filter status: ACTIVE<br />
</pre><br />
<br />
== For SpamAssassin ==<br />
<br />
Open the following file in Linux editor<br />
<pre><br />
$ /opt/open-xchange/etc/imap.properties<br />
</pre><br />
<br />
Edit the following parameter to:<br />
<br />
<pre><br />
com.openexchange.imap.spamHandler=SpamAssassin <br />
</pre><br />
<br />
Once done then reboot the OX Service<br />
<pre><br />
$ /etc/init.d/open-xchange restart<br />
</pre><br />
<br />
Make sure that SpamAssassin port is also open Port 783 (by default). Also verify that spam bundles loaded successfully.<br />
<br />
<pre><br />
$ /opt/open-xchange/sbin/listbundles | grep spam <br />
bundlename: com.openexchange.spamhandler.spamassassin status: ACTIVE <br />
</pre><br />
<br />
<br />
Finally, we will need to enable the capabilities for SPAM. To do this we have to run the following command for e.g.<br />
<br />
<pre><br />
$ changeuser -A oxadmin -P admin_password -c contextID -u username --gui_spam_filter_capabilities_enabled true <br />
</pre><br />
<br />
or to set the property <tt>com.openexchange.spamhandler.enabled</tt> to <tt>true</tt> via ConfigCascade<br />
<br />
[[Category: Administrator]]<br />
<br />
[[Category: OX6]]<br />
[[Category: AppSuite]]<br />
<br />
[[Category: Spamhandling]]<br />
<br />
= Basic Troubleshooting =<br />
<br />
1. Make sure that you configure your Firewall to allow ports e.g. '''Port 4190''' for Sieve and '''Port 783''' for SpamAssassin in your Server environment.<br />
<br />
2. Check '''/var/log/maillog''' for any issues as well. Also can turn the mail Debug logging for Dovecot e.g.<br />
<br />
<pre><br />
$ vi /etc/dovecot/conf.d/10-logging.conf <br />
</pre><br />
and change the config parameter<br />
<br />
<pre><br />
$ mail_debug = yes<br />
</pre><br />
<br />
3. For SpamAssassin, you can also check the Open-Xchange Server logs to make sure that the settings are loaded correctly.</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Spamexperts&diff=22885Spamexperts2017-02-14T10:38:03Z<p>Martin.schneider: /* Provisioning */</p>
<hr />
<div>= Introduction =<br />
<br />
This package connects the [http://www.spamexperts.com/ SpamExperts] system with Open-Xchange.<br />
It allows to access your SpamExperts settings from within Open-Xchange and use the spam- and ham<br />
learning mechanisms of SpamExperts directly from within the Open-Xchange UI.<br />
<br />
{{InstallPlugin|pluginname=open-xchange-spamhandler-spamexperts open-xchange-spamhandler-spamexperts-gui|sopath=6.22/backend|version=v6.22.x}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-spamhandler-spamexperts open-xchange-appsuite-spamexperts|toplevel=products|sopath=appsuite/stable/backend|version=App Suite}}<br />
<br />
=Components= <br />
<br />
== OX UI Plugin ==<br />
<br />
The UI plugin extends the OX settings tree with a new subtree to access the "Antispam" management WEB UI of Spamexperts.com<br />
<br />
== OX Backend Plugin ==<br />
<br />
The backend plugin consists of a servlet which can create an authentication ticket for the currently active OX user by using the <br />
Spamexperts.com API and then sends the ticket back to the UI plugin which will do the redirect to the external Spamexperts.com management WEB UI.<br />
<br />
= Configuration =<br />
<br />
You need to adapt the settings in <tt>/opt/open-xchange/etc/spamexperts.properties</tt><br />
<br />
Settings can be separated in two sections:<br />
<br />
== SpamExperts UI integration ==<br />
<br />
Define your custom parameters in order to integrate your branded SpamExperts UI into Open-Xchange<br />
<br />
== SpamExperts SPAM/HAM learning integration ==<br />
<br />
'''Note: This requires backend version 7.6.0 or newer.'''<br />
<br />
Configure you personal parameters to access the SpamExperts IMAP server in order to use the SPAM/HAM<br />
learning mechanism.<br />
<br />
In addition, you have to tell the Open-Xchange mail backend what spamhandler to use for SPAM/HAM learning.<br />
This must be done in the configuration file <tt>/opt/open-xchange/etc/imap.properties</tt>. You have to set<br />
<br />
com.openexchange.imap.spamHandler=SpamExperts<br />
<br />
exactly like this, or the SPAM/HAM learning mechanism will not work.<br />
<br />
= Provisioning =<br />
<br />
'''Note: This requires backend version 7.6.0 or newer.'''<br />
<br />
In order to activate SPAM/HAM learning in OX Webmail, you have to turn that on for the users by using one of the following ways:<br />
<br />
* using create- or changeuser, provide the option <tt>--gui_spam_filter_capabilities_enabled true</tt> or<br />
* setting <tt>com.openexchange.spamhandler.enabled</tt> to <tt>true</tt> via ConfigCascade<br />
<br />
In order to add the spamexperts link to OX Webmail, provide the option <tt>--capabilities-to-add com.spamexperts</tt><br />
<br />
[[Category: Administrator]]<br />
<br />
[[Category: OX6]]<br />
[[Category: AppSuite]]<br />
<br />
[[Category: Spamhandling]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXSessionSecurityFeatures&diff=22360OXSessionSecurityFeatures2016-08-31T15:12:12Z<p>Martin.schneider: fixed typos</p>
<hr />
<div>== Security features in session handling ==<br />
<br />
This page gives an overview of the security features of OX session handling, and the ways to configure them. Since a session represents an authenticated user it's important that we make sure a session is only used by the person having created it. We ensure this in a variety of ways. <br />
<br />
=== Use HTTPS ===<br />
<br />
This is probably the most important hint. When using HTTPS the traffic between the browser and backend is encrypted, and unless someone has the servers private key on hand, no one can snoop around in the headers and body of the request. Also when using HTTPS the OX server marks its cookies so that they may ONLY be transferred using an HTTPS transport. This will protect the '''Session Secret''', and, when using autologin, the '''Session ID''' from being read by others. <br />
<br />
=== IPCheck ===<br />
<br />
When the '''IP Check''' is enabled, the OX server records the IP address of the client that created the session. Only requests coming from that IP address may then use the session. This is great for protecting the session from being taken over by someone else. It falls a little short when the accesses are bundled up by a proxy and becomes a nuisance when the client frequently changes IP addresses (mobile phones that roam a lot being the canonical example). In any case we suggest leaving the IP check active. The file '''server.properties''' contains the configuration for this:<br />
<br />
com.openexchange.IPCheck=true<br />
<br />
<br />
=== HTTP Only Cookies ===<br />
<br />
Normally code running in the browser may access the cookies for the domain the page was loaded from. To urge a browser not to pass cookies on to javascript code, cookies may contain the Http-Only flag. Since the OX cookies are only relevant for the communication of the browser with the server (the frontend need not know their content), it's wise to set this flag. Sometimes, though, browsers may balk at this property, so you have the option of turning this off, though normally, you shouldn't be required to do so. Again, this can be configured in the '''server.properties''':<br />
<br />
com.openexchange.cookie.httpOnly=true<br />
<br />
<br />
=== Cookie Hash ===<br />
<br />
The '''cookie hash''' has a dual role:<br />
<br />
# It prevents OX cookies from overwriting each other when two clients use the same cookie store (e.g. the browser itself and a browser plugin)<br />
# It serves as a fingerprint of the client<br />
<br />
The '''cookie hash''' is usually calculated using the '''client''' parameter and the '''User-Agent''' header. The '''client''' is then stored along with the session in the OX backend. When another request comes along, the hash is recalculated using the '''User-Agent''' header of the new request and the stored '''client''' value. It therefore verifies that the User-Agent header is the same. You can finetune this process a bit. <br />
<br />
The first thing you can influence is, which headers are used in constructing the cookie hash. '''User-Agent''' is a given, further headers can be added using the '''com.openexchange.cookie.hash.fields''' parameter. It contains a comma separated list of header names to be included in the hash calculation. Say, for example, your apache configuration creates a client fingerprint and sets the header X-Security-ClientFingerprint (a hypothetical example), and you want to OX server to use this when verifying the session integrity. Open up the '''server.properties''' and set the following configuration option:<br />
<br />
com.openexchange.cookie.hash.fields=X-Security-ClientFingerprint<br />
<br />
The OX server will then use the User-Agent header, the client parameter and the X-Security-ClientFingerprint header to ensure the session is only used by the same client.<br />
<br />
The second thing you can configure is whether the hash value should be calculated and checked on every request. In essence setting this property to anything else than '''calculate''' removes the second role of the cookie hash. It might be needed if you use an exotic authentication mechanism, where sessions are created by a different client than the one using the session, or if clients for one reason or another switch the value of the User-Agent header during a session. The configuration parameter '''com.openexchange.cookie.hash''' can be set either to '''calculate''' (the default), meaning the fingerprinting mechanism will be used or '''remember''' meaning only the first role will be fulfilled. Again, this can be set in the file '''server.properties''':<br />
<br />
com.openexchange.cookie.hash=calculate</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=22125HTTP API2016-07-05T09:33:48Z<p>Martin.schneider: Provide 'old style' HTTP API until new documentation is useful</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 />
* for POST requests all described parameters are normally expected in the request body, exceptions are documented,<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 are normally expected in the POST request body:<br />
* <code>name</code> – The login name.<br />
* <code>password</code> – The password MUST be placed in the request body, otherwise the login request will be denied.<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 />
=== Autologin ===<br />
<br />
If the session ID was stored in a cookie before via the [[#Refresh_auto-login_cookie | store request]], the user can reuse his old session by using the autologin request.<br />
<br />
GET <code>/ajax/login?action=autologin</code><br />
<br />
Parameters:<br />
<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.<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 />
<br />
Response: A JSON object containing the session ID used for all subsequent requests.<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>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 "left-hand" limit of the range to return<br />
* <code>right_hand_limit</code> - A positive integer number to specify the "right-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 />
| 654 || original_id || String || The original mail identifier (e.g. if fetched from "virtual/all" folder).<br />
|-<br />
| 655 || original_folder_id || String || The original folder identifier (e.g. if fetched from "virtual/all" folder).<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 "left-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 "right-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 />
<br />
=== Search mails (alternative) ===<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 mails 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 object containing filters. <code>{"filter":<i>[search term]</i>}</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: "from" }</code>. The available field names are <code>from</code>, <code>to</code>, <code>cc</code>, <code>bcc</code>, <code>subject</code>, <code>received_date</code>, <code>sent_date</code>, <code>size</code>,<code>flags</code>, <code>content</code>, <code>content_type</code>, <code>disp</code> and <code>priority</code> as defined in [[#DetailedMailData | Detailed mail data]]. 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 />
<code><br />
{"filter":<br />
["or",<br />
["and",<br />
["=", {"field":"to"}, "test1@example.org"],<br />
["not",<br />
["=", {"field":"from"}, "test2@example.org"]<br />
],<br />
[">", {"field":"received_date"}, "1458063382000"]<br />
],<br />
["=", {"field":"subject"}, "TestSubject"]<br />
]<br />
}<br />
</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 />
=== 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 />
* <code>lineWrapAfter</code> – An integer value specifying the line-wrap setting (only effective for plain-text content); if absent the setting is taken from user's mail settings. Available with v7.8.1.<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>folder</code> (optional) – The folder ID to restrict the search to. If not specified, all folders are searched.<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: The search pattern string in a JSON object named "pattern".<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 />
=== Check if file name is valid (since 7.8.1, Preliminary) ===<br />
<br />
GET <code>/ajax/infostore?action=checkname</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>name</code> – Name of the file to check.<br />
<br />
Response: An empty JSON object when file name is valid.<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>offset</code> – Optionally sets the start offset in bytes where to append the data to the document, must be equal to the actual document's length (available with v7.8.1). Only available if the underlying [[#FileStorageAccount | File storage account]] supports the "RANDOM_FILE_ACCESS" capability.<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 />
| 1044 || mail_starttls || Boolean || '''Available since v7.8.2''' Whether to establish a secure connection to mail server via STARTTLS.<br />
|-<br />
| 1045 || transport_starttls || Boolean || '''Available since v7.8.2''' Whether to establish a secure connection to transport server via STARTTLS.<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 />
POST <code>/ajax/autoconfig?action=get</code><br />
<br />
application/x-www-form-urlencoded 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 />
* <code>force_secure</code> – '''Available since v7.8.2''' Enforce a secure connection for configured mail account, default is true (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 />
| capabilities || List of Strings || A list of capability names. Possible values are: "FILE_VERSIONS", "EXTENDED_METADATA", "RANDOM_FILE_ACCESS", "LOCKS" <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>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=22109HTTP API2016-06-30T08:29:52Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>This page has been moved to [https://documentation.open-xchange.com/latest/middleware/http_api.html documentation.open-xchange.com]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Writing_a_simple_application_with_embedded_iframe&diff=22108AppSuite:Writing a simple application with embedded iframe2016-06-30T08:03:45Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div><!-- !!! --><br />
<!-- PLEASE APPLY CHANGES ONLY TO THE NEW TECHNICAL DOCUMENTATION: wd/frontend/web/documentation --> <br />
<!-- !!! --><br />
<br />
{{Stability-experimental}}<br />
<br />
<div class="title">Writing a simple application with an embedded iframe and launcher link</div><br />
<br />
__TOC__<br />
<br />
==Provide an iframe for the content area (since 7.8)==<br />
<br />
Developing an app with an iframe for the content area is quite easy.<br />
All it needs is a manifest file (manifest.json) and the app file (main.js).<br />
<br />
Both should be located in an designated folder in the apps folder. <br />
In this example the namespace 'com.example' will be used. (apps/com.example)<br />
<br />
To make use of the provided helper function io.ox/core/tk/iframe has to be required in the define section.<br />
<br />
<pre class="language-javascript"><br />
define('com.example/main', [<br />
'io.ox/core/tk/iframe',<br />
'gettext!com.example'<br />
], function (createIframeApp, gt) {<br />
<br />
'use strict';<br />
<br />
var iframeApp = createIframeApp({<br />
name: 'com.example', // the name of the app<br />
title: gt('Hallo, World!'), // the title of the app as used in the launcher<br />
pageTitle: gt('Hallo, World!'), // the page Title<br />
url: 'https://www.example.com/', // the domain which should be used for the iframe <br />
acquireToken: true // generates a login token and appends it to the supplied url as ox_token parameter<br />
});<br />
<br />
return {<br />
getApp: iframeApp.getApp<br />
};<br />
});<br />
</pre><br />
<br />
The provided token can be used to generate a valid session with the [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (redeem token login process)].<br />
<br />
==Add app to the launcher (since 7.8)==<br />
<br />
To display an app in the launcher, the property 'topbar': true has to be set in the manifest.json file of the app.<br />
To define the order, use the index value in the manifest.json file.<br />
<br />
<pre class="language-javascript"><br />
{<br />
"title": "Hallo, World!",<br />
"company": "external",<br />
"icon": "/images/icon.png",<br />
"category": "Dev",<br />
"settings": false,<br />
"index": 10000,<br />
"topbar": true<br />
}<br />
</pre><br />
<br />
==Reorder / remove apps from launcher (since 7.6)==<br />
<br />
To define a custom order of the apps or remove an app from the laucher the server-side setting topbar/order can be used to provide a comma-separated list of apps which should be available in the launcher.<br />
<br />
Example: io.ox/core//topbar/order=io.ox/mail,com.example,io.ox/contacts,io.ox/portal<br />
<br />
An app which is not listed here, is not available in the launcher anymore.</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Metrics-Events&diff=22107AppSuite:Metrics-Events2016-06-30T08:03:12Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>{{Version|7.8.0}}<br />
<br />
== Metrics - Events ==<br />
<br />
A list of all tracked events identified with their composite id (app, ui element, action, detail). Please notice that words within box brackets are used as placeholders. <br />
<br />
For more information please visit he other metrics articles [[Category:Metrics]].<br />
<br />
=== General ===<br />
<br />
''Placeholders''<br />
<br />
[action] the data-action property of the action node<br />
<br />
==== Header/Logo ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/banner/title<br />
| Click on header title<br />
|-<br />
| core/banner/logo<br />
| Click on header logo<br />
|}<br />
<br />
==== File Viewer ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/viewer/toolbar/[action]<br />
| User clicks on action while using the file viewer<br />
|}<br />
<br />
==== Settings ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/toolbar/[action] <br />
| Upsell event triggered<br />
|-<br />
| settings/folder/select/[type] <br />
| Click on a specific folder/part in the setting<br />
|}<br />
<br />
==== Help ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/toolbar/help/[type] <br />
| Help action was clicked<br />
|}<br />
<br />
==== Guided Tours ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/toolbar/guided-tour/[type]<br />
| Click on 'Start guided tour for this app'<br />
|}<br />
<br />
==== Loadtime ====<br />
<br />
A event triggers when an app started. The measure time is between the click on the app launcher and the moment the app was loaded (via ox.launch) <br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/loadtime/[appname]/[time]<br />
| Click on app launcher<br />
|}<br />
<br />
<br />
==== Client Onboarding ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/client-onboarding/platform/select <br />
| Click on platform within wizard dialog (1. Step)<br />
|-<br />
| core/client-onboarding/device/select <br />
| Click on device within wizard dialog (2. Step)<br />
|-<br />
| core/client-onboarding/scenario/select <br />
| Click on scenario within wizard dialog (3. Step)<br />
|-<br />
| core/client-onboarding/action/select <br />
| Click on action within wizard dialog (3. Step)<br />
|-<br />
| core/client-onboarding/action/execut <br />
| Click on action button (3. Step)<br />
|-<br />
| core/client-onboarding/mode/toggle<br />
| Toggle normal and expert mode<br />
|}<br />
<br />
==== Upsell ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| core/upsell/[upsell.type]/[upsell.id]<br />
| Clicks (settings, my contact data, help, getting started, fullscreen, about, sign out) within the context menu of our settings icon at the top right.<br />
|}<br />
<br />
=== Apps ===<br />
<br />
==== Portal ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| portal/toolbar/add/[type] <br />
| Click on “Add widget” button in upper right area of portal. <br />
|-<br />
| portal/toolbar/add/[type]<br />
| Click on a specific widget to “install” it on the portal page.<br />
|-<br />
| portal/widgets/show-detail/[type]<br />
| Click on the area of the widget, which gets displayed.<br />
|-<br />
| portal/widget/disable/[type]<br />
| Click on the remove widget icon (“X”)<br />
|-<br />
| portal/widget/change-order/[type]<br />
| Reordering a widget into another location on the screen. <br />
|}<br />
<br />
==== Mail ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| mail/list/[layout]/select/one<br> mail/list/[layout]/select/mulitple <br />
| Select mail by click on the list/grid (layout: vert, horiz, compact, list)<br />
|-<br />
| mail/toolbar/[action]<br>mail/detail/toolbar/[action]<br> mail/compose/toolbar/[action]<br />
| Clicks on a email action<br />
|-<br />
| mail/folders/folder/select/[type] <br />
| Clicks on a folder in the mail folder tree (type: primary, external) <br />
|-<br />
| mail/folder/account/add<br />
| Clicks on “Add new mail account”<br />
|-<br />
| mail/settings/account/add <br />
| Clicks within “Social + Mail Accounts” on “Add account” <br />
|}<br />
<br />
==== Contacts ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| contacts/list/select/one<br> contacts/list/select/multiple <br />
| Select contact by click on the list/grid<br />
|-<br />
| contacts/folder/select/[type]<br />
| Clicks on a folder in the contact folder tree (folder-type: private, public, shared)<br />
|-<br />
| contacts/toolbar/[action]<br />
| Clicks on a a contact action <br />
|}<br />
<br />
==== Calendar ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| calendar/toolbar/[action] <br />
| Clicks on calendar toolbar action <br />
|-<br />
| calendar/[layout-mode]/select <br />
| Clicks on appointments within non-list layout modes <br />
|-<br />
| calendar/[layout-mode]/create <br />
| Clicks on blank space within non-list layout modes to create appointment<br />
|-<br />
| calendar/folder/select/[type] <br />
| Clicks on a folder in the contact folder tree (folder-type: private, public, shared)<br />
|-<br />
| calendar/folder/permissions <br />
| Clicks on the “cloud” icon and the “User” icon next to the folder name <br />
|-<br />
| calendar/folder/context-menu/[action]<br />
| Clicks within the context menu, which pops up, when you click on a folder name and its menu icon<br />
|-<br />
| calendar/detail/toolbar/[action] <br />
| Clicks on calendar detail view toolbar action <br />
|}<br />
<br />
==== Tasks ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| tasks/folder/select/[type]<br />
| Clicks on a folder in the contact folder tree (folder-type: private, public, shared)<br />
|-<br />
| tasks/folder/context-menu/[action]<br />
| Clicks within the context menu, which pops up, when you click on a folder name and its menu icon<br />
|-<br />
| tasks/toolbar/[action]<br />
| Clicks on tasks toolbar action <br />
|-<br />
| tasks/detail/[action]<br />
| Clicks on task detail view toolbar action <br />
|}<br />
<br />
==== Drive ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| drive/folder/select/[type] <br />
| Clicks on a folder in drive folder tree (folder-type: [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (standard_folder_type)] + '.' + [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (folder_type)])<br />
|-<br />
| drive/folder/context-menu/[action]<br />
| Clicks within the context menu, which pops up, when you click on a folder name and its menu icon<br />
|-<br />
| drive/toolbar/[action] <br />
| Clicks on drive toolbar action <br />
|}<br />
<br />
==== Text App (aka Text Portal)====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| text-portal/toolbar/[action]<br />
| Clicks on Text App toolbar action (text-newblank, text-open)<br />
|-<br />
| text-portal/recentlist/[action]<br />
| Clicks on documents in the recent list (text-edit)<br />
|-<br />
| text-portal/templates/[action]<br />
| Clicks on templates (text-newfromtemplate, text-newblank)<br />
|}<br />
<br />
==== Spreadsheet App (aka Spreadsheet Portal)====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| spreadsheet-portal/toolbar/[action]<br />
| Clicks on Spreadsheet App toolbar action (spreadsheet-newblank, spreadsheet-open)<br />
|-<br />
| spreadsheet-portal/recentlist/[action]<br />
| Clicks on documents in the recent list (spreadsheet-edit)<br />
|-<br />
| spreadsheet-portal/templates/[action]<br />
| Clicks on templates (spreadsheet-newfromtemplate, spreadsheet-newblank)<br />
|}<br />
<br />
==== Text Editor ====<br />
<br />
{| class="wikitable"<br />
! style="font-weight: bold;" | EventId<br />
! style="font-weight: bold;" | Trigger<br />
|-<br />
| text-editor/toolbar/[action]<br />
| Clicks on Text Editor toolbar nyi<br />
|}<br />
<br />
<br />
[[Category:AppSuite]]<br />
[[Category:UI]]<br />
[[Category:Metrics]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OX_Drive_API&diff=22106OX Drive API2016-06-30T08:02:10Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div><div class="title">OX Drive API</div><br />
<br />
__TOC__<br />
<br />
= Introduction =<br />
<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 />
The synchronization is based on checksums for files and folders, differences between the server- and client-side are determined using a three-way comparison of server, client and previously acknowledged file- and directory-versions. The synchronization logic is performed by the server, who instructs the client with a set of actions that should be executed in order to come to a synchronized state. <br />
<br />
Therefore, the client takes a snapshot of it's local files and directories, calculates their checksums, and sends them as a list to the server, along with a list of previously acknowledged checksums. The server takes a similar snapshot of the files and directories on the underlying file storages and evaluates which further actions are necessary for synchronization. After executing the server-side actions, the client receives a list of actions that should be executed on the client-side. These steps are repeated until the server-state matches the client-state. <br />
<br />
Key concept is that the synchronization works stateless, i.e. it can be interrupted and restarted at any time, following the eventual consistency model. <br />
<br />
Entry point for the synchronization is the [[#Synchronize_folders|<code>syncfolders</code>]] request, where the directories are compared, and further actions are determined by the server, amongst others actions to synchronize the files in a specific directory using the [[#Synchronize_files_in_a_folder|<code>syncfiles</code>]] request. After executing the actions, the client should send another <code>syncfolders</code> request to the server and execute the returned actions (if present), or finish the synchronization if there are no more actions to execute. In pseudo-code, the synchronization routine could be implemented as follows:<br />
<br />
WHILE TRUE<br />
{<br />
response = SYNCFOLDERS()<br />
IF 0 == response.actions.length<br />
BREAK<br />
ELSE<br />
EXECUTE(response.actions)<br />
}<br />
<br />
Basically, it's up to the client how often such a synchronization cycle is initiated. For example, he could start a new synchronization cycle after a fixed interval, if he recognizes that the client directories have changed, or if he is informed that something has changed on the server by an event. It's also up to the client to interrupt the synchronization cycle at any time during execution of the actions and continue later on, however, it's recommended to start a new synchronization cycle each time to avoid possibly outdated actions.<br />
<br />
= API =<br />
<br />
As part of the [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API], the basic conventions for exchanging messages described there are also valid for this case, especially the [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (low level protocol)] and [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (error handling)]. Each request against the Drive API assumes a valid server session that is uniquely identified by the session id and the corresponding cookies and are sent with each request. A new session can be created via the [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (login module)].<br />
<br />
The root folder plays another important role for the message exchange. The root folder has a unique identifier. It is the parent server folder for the synchronization. All path details for directories and files are relative to this folder. This folder's id is sent with each request. To select the root folder during initial client configuration, the client may get a list of synchronizable folders with the [[#Get_synchronizable_Folders|<code>subfolders</code>]] action.<br />
<br />
Subsequently all transferred objects and all possible actions are listed.<br />
<br />
== File Version ==<br />
<br />
A file in a directory is uniquely identified by its filename and the checksum of its content. <br />
<br />
{| id="FileVersion" cellspacing="0" border="1"<br />
|+ align="bottom" | File Version<br />
! Name !! Type !! Value<br />
|-<br />
| name || String || The name of the file, including its extension, e.g. <code>test.doc</code>.<br />
|-<br />
| checksum || String || The MD5 hash of the file, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.<br />
|}<br />
<br />
== Directory Version ==<br />
<br />
A directory is uniquely identified by its full path, relative to the root folder, and the checksum of its content. <br />
<br />
{| id="DirectoryVersion" cellspacing="0" border="1"<br />
|+ align="bottom" | Directory Version<br />
! Name !! Type !! Value<br />
|-<br />
| path || String || The path of the directory, including the directory's name, relative to the root folder, e.g. <code>/sub/test/letters</code>.<br />
|-<br />
| checksum || String || The MD5 hash of the directory, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.<br />
|}<br />
<br />
Note: the checksum of a directory is calculated based on its contents in the following algorithm:<br />
<br />
* Build a list containing each file in the directory (not including subfolders or files in subfolders)<br />
* Ensure a lexicographically order in the following way:<br />
** Normalize the filename using the <code>NFC</code> normalization form (canonical decomposition, followed by canonical composition) - see http://www.unicode.org/reports/tr15/tr15-23.html for details<br />
** Encode the filename to an array of UTF-8 unsigned bytes (array of codepoints)<br />
** Compare the filename (encoded as byte array "fn1") to another one "fn2" using the following comparator algorithm:<br />
<br />
min_length = MIN(LENGTH(fn1), LENGTH(fn2))<br />
FOR i = 0; i < min_length; i++ <br />
{<br />
result = fn1[i] - fn2[i]<br />
IF 0 != result RETURN result<br />
}<br />
RETURN LENGTH(fn1) - LENGTH(fn2)<br />
<br />
* Calculate the aggregated MD5 checksum for the directory based on each file in the ordered list:<br />
** Append the file's NFC-normalized (see above) name, encoded as UTF-8 bytes<br />
** Append the file's MD5 checksum string, encoded as UTF-8 bytes<br />
<br />
== Actions ==<br />
<br />
All actions are encoded in the following format. Depending on the action type, not all properties may be present.<br />
<br />
{| id="Actions" cellspacing="0" border="1"<br />
|+ align="bottom" | Actions<br />
! Name !! Type !! Value<br />
|-<br />
| action || String || The type of action to execute, currently one of <code>acknowledge</code>, <code>edit</code>, <code>download</code>, <code>upload</code>, <code>remove</code>, <code>sync</code>, <code>error</code>.<br />
|-<br />
| version || Object || The (original) file- or directory-version referenced by the action.<br />
|-<br />
| newVersion || Object || The (new) file- or directory-version referenced by the action.<br />
|-<br />
| path || String || The path to the synchronized folder, relative to the root folder.<br />
|-<br />
| root || String || The corresponding root folder identifier (optional, available since API version 5).<br />
|-<br />
| offset || Number || The requested start offset in bytes for file uploads.<br />
|-<br />
| totalLength || Number || The total length in bytes for file downloads.<br />
|-<br />
| contentType || String || The file's content type for downloads (deprecated, available until API version 2).<br />
|-<br />
| created || Timestamp || The file's creation time (always UTC, not translated into user time).<br />
|-<br />
| modified || Timestamp || The file's last modification time (always UTC, not translated into user time).<br />
|-<br />
| error || Object || The error object in case of synchronization errors.<br />
|-<br />
| quarantine || Boolean || The flag to indicate whether versions need to be excluded from synchronization.<br />
|-<br />
| reset || Boolean || The flag to indicate whether locally stored checksums should be invalidated. <br />
|-<br />
| stop || Boolean || The flag to signal that the client should stop the current synchronizsation cycle. <br />
|-<br />
| acknowledge || Boolean || The flag to signal if the client should not update it's stored checksums when performing an <code>EDIT</code> action. <br />
|-<br />
| thumbnailLink || String || A direct link to a small thumbnail image of the file if available (deprecated, available until API version 2). <br />
|-<br />
| previewLink || String || A direct link to a medium-sized preview image of the file if available (deprecated, available until API version 2). <br />
|-<br />
| directLink || String || A direct link to the detail view of the file in the web interface (deprecated, available until API version 2). <br />
|-<br />
| directLinkFragments || String || The fragments part of the direct link (deprecated, available until API version 2). <br />
|}<br />
<br />
The following list gives an overview about the used action types:<br />
<br />
=== <code>acknowledge</code> ===<br />
Acknowledges the successful synchronization of a file- or directory version, i.e., the client should treat the version as synchronized by updating the corresponding entry in its metadata store and including this updated information in all following <code>originalVersions</code> arrays of the <code>syncfiles</code> / <code>syncfolders</code> actions. Depending on the <code>version</code> and <code>newVersion</code> parameters of the action, the following acknowledge operations should be executed (exemplarily for directory versions, file versions are acknowledged in the same way):<br />
<br />
* Example 1: Acknowledge a first time synchronized directory <br /> The server sends an <code>acknowledge</code> action where the newly synchronized directory version is encoded in the <code>newVersion</code> parameter. The client should store the version in his local checksum store and send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests.<br />
{<br />
"action" : "acknowledge",<br />
"newVersion" : {<br />
"path" : "/",<br />
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"<br />
}<br />
}<br />
<br />
* Example 2: Acknowledge a synchronized directory after updates <br /> The server sends an <code>acknowledge</code> action where the previous directory version is encoded in the <code>version</code>, and the newly synchronized directory in the <code>newVersion</code> parameter. The client should replace any previously stored entries of the directory version in his local checksum store with the updated version, and send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests.<br />
{<br />
"action" : "acknowledge",<br />
"newVersion" : {<br />
"path" : "/",<br />
"checksum" : "7bb1f1a550e9b9ab4be8a12246f9d5fb"<br />
},<br />
"version" : {<br />
"path" : "/",<br />
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"<br />
}<br />
}<br />
<br />
* Example 3: Acknowledge the deletion of a previously synchronized directory <br /> The server sends an <code>acknowledge</code> where the <code>newVersion</code> parameter is set to <code>null</code> to acknowledge the deletion of the previously synchronized directory version as found in the <code>version</code> parameter. The client should remove any stored entries for this directory from his local checksum store, and no longer send this version in the <code>originalVersions</code> array in upcoming <code>syncfolders</code> requests. <br /> Note that an acknowledged deletion of a directory implicitly acknowledges the deletion of all contained files and subfolders, too, so the client should also remove those <code>originalVersion</code>s from his local checksum store.<br />
{<br />
"action" : "acknowledge",<br />
"version" : {<br />
"path" : "/test",<br />
"checksum" : "3525d6f28eb8cb30eb61ab7932367c35"<br />
}<br />
}<br />
<br />
=== <code>edit</code> ===<br />
Instructs the client to edit a file- or directory version. This is used for move/rename operations. The <code>version</code> parameter is set to the version as sent in the <code>clientVersions</code> array of the preceding <code>syncfiles</code>/<code>syncfolders</code> action. The <code>newVersion</code> contains the new name/path the client should use. Unless the optional boolean parameter <code>acknowledge</code> is set to <code>false</code> an <code>edit</code> action implies that the client updates its known versions store accordingly, i.e. removes the previous entry for <code>version</code> and adds a new entry for <code>newVersion</code>.<br />
When editing a directory version, the client should implicitly take care to create any not exisiting subdirectories in the <code>path</code> of the <code>newVersion</code> parameter.<br />
A concurrent client-side modification of the file/directory version can be detected by the client by comparing the current checksum against the one in the passed <code>newVersion</code> parameter.<br />
<br />
* Example 1: Rename a file <br /> The server sends an <code>edit</code> action where the source file is encoded in the <code>version</code>, and the target file in the <code>newVersion</code> parameter. The client should rename the file identified by the <code>version</code> parameter to the name found in the <code>newVersion</code> parameter. Doing so, the stored checksum entry for the file in <code>version</code> should be updated, too, to reflect the changes.<br />
{<br />
"path" : "/",<br />
"action" : "edit",<br />
"newVersion" : {<br />
"name" : "test_1.txt",<br />
"checksum" : "03395a94b57eef069d248d90a9410650"<br />
},<br />
"version" : {<br />
"name" : "test.txt",<br />
"checksum" : "03395a94b57eef069d248d90a9410650"<br />
}<br />
}<br />
<br />
* Example 2: Move a directory <br /> The server sends an <code>edit</code> action where the source directory is encoded in the <code>version</code>, and the target directory in the <code>newVersion</code> parameter. The client should move the directory identified by the <code>version</code> parameter to the path found in the <code>newVersion</code> parameter. Doing so, the stored checksum entry for the directory in <code>version</code> should be updated, too, to reflect the changes.<br />
{<br />
"action" : "edit",<br />
"newVersion" : {<br />
"path" : "/test2",<br />
"checksum" : "3addd6de801f4a8650c5e089769bdb62"<br />
},<br />
"version" : {<br />
"path" : "/test1/test2",<br />
"checksum" : "3addd6de801f4a8650c5e089769bdb62"<br />
}<br />
}<br />
<br />
* Example 3: Rename a conflicting file <br /> The server sends an <code>edit</code> action where the original client file is encoded in the <code>version</code>, and the target filename in the <code>newVersion</code> parameter. The client should rename the file identified by the <code>version</code> parameter to the new filename found in the <code>newVersion</code> parameter. If the <code>acknowledge</code> parameter is set to <code>true</code> or is not set, the stored checksum entry for the file in <code>version</code> should be updated, too, to reflect the changes, otherwise, as in this example, no changes should be done to the stored checksums.<br />
{<br />
"action" : "edit",<br />
"version" : {<br />
"checksum" : "fade32203220752f1fa0e168889cf289",<br />
"name" : "test.txt"<br />
},<br />
"newVersion" : {<br />
"checksum" : "fade32203220752f1fa0e168889cf289",<br />
"name" : "test (TestDrive).txt"<br />
},<br />
"acknowledge" : false,<br />
"path" : "/"<br />
}<br />
<br />
=== <code>download</code> ===<br />
Contains information about a file version the client should download. For updates of existing files, the previous client version is supplied in the <code>version</code> parameter. For new files, the <code>version</code> parameter is omitted. The <code>newVersion</code> holds the target file version, i.e. filename and checksum, and should be used for the following <code>download</code> request. The <code>totalLength</code> parameter is set to the file size in bytes, allowing the client to recognize when a download is finished. Given the supplied checksum, the client may decide on its own if the target file needs to be downloaded from the server, or can be created by copying a file with the same checksum to the target location, e.g. from a trash folder. The file's content type can be retrieved from the <code>contentType</code> parameter, similar to the file's creation and modification times that are availble in the <code>created</code> and <code>modified</code> parameters.<br />
<br />
* Example 1: Download a new file <br /> The server sends a <code>download</code> action where the file version to download is encoded in the <code>newVersion</code> paramter. The client should download and save the file as indicated by the <code>name</code> property of the <code>newVersion</code> in the directory identified by the supplied <code>path</code>. After downloading, the <code>newVersion</code> should be added to the client's known file versions database. <br />
{<br />
"totalLength" : 536453,<br />
"path" : "/",<br />
"action" : "download",<br />
"newVersion" : {<br />
"name" : "test.pdf",<br />
"checksum" : "3e0d7541b37d332c42a9c3adbe34aca2"<br />
},<br />
"contentType" : "application/pdf",<br />
"created" : 1375276738232,<br />
"modified" : 1375343720985<br />
}<br />
<br />
* Example 2: Download an updated file <br /> The server sends a <code>download</code> action where the previous file version is encoded in the <code>version</code>, and the file version to download in the <code>newVersion</code> parameter. The client should download and save the file as indicated by the <code>name</code> property of the <code>newVersion</code> in the directory identified by the supplied <code>path</code>, replacing the previous file. After downloading, the <code>newVersion</code> should be added to the client's known file versions database, replacing an existing entry for the previous <code>version</code>.<br />
{<br />
"totalLength" : 1599431,<br />
"path" : "/",<br />
"action" : "download",<br />
"newVersion" : {<br />
"name" : "test.pdf",<br />
"checksum" : "bb198790904f5a1785d7402b0d8c390e"<br />
},<br />
"contentType" : "application/pdf",<br />
"version" : {<br />
"name" : "test.pdf",<br />
"checksum" : "3e0d7541b37d332c42a9c3adbe34aca2"<br />
},<br />
"created" : 1375276738232,<br />
"modified" : 1375343720985<br />
}<br />
<br />
=== <code>upload</code> ===<br />
Instructs the client to upload a file to the server. For updates of existing files, the previous server version is supplied in the <code>version</code> parameter, and should be used for the following <code>upload</code> request. For new files, the <code>version</code> parameter is omitted. The <code>newVersion</code> holds the target file version, i.e. filename and checksum, and should be used for the following <code>upload</code> request. When resuming a previously partly completed upload, the <code>offset</code> parameter contains the offset in bytes from which the file version should be uploaded by the client. If possible, the client should set the <code>contentType</code> parameter for the uploaded file, otherwise, the content type falls back to <code>application/octet-stream</code>.<br />
<br />
=== <code>remove</code> ===<br />
Instructs the client to delete a file or directory version. The <code>version</code> parameter contains the version to delete. A deletion also implies a removal of the corresponding entry in the client's known versions store.<br />
A concurrent client-side modification of the file/directory version can be detected by comparing the current checksum against the one in the passed <code>version</code> parameter.<br />
<br />
* Example 1: Remove a file <br /> The server sends a <code>remove</code> action where the file to be removed is encoded as <code>version</code> parameter. The <code>newVersion</code> parameter is not set in the action. The client should delete the file identified by the <code>version</code> parameter. A stored checksum entry for the file in <code>version</code> should be removed, too, to reflect the changes. The <code>newVersion</code> parameter is not set in the action.<br />
{<br />
"path" : "/test2",<br />
"action" : "remove",<br />
"version" : {<br />
"name" : "test.txt",<br />
"checksum" : "03395a94b57eef069d248d90a9410650"<br />
}<br />
}<br />
<br />
* Example 2: Remove a directory <br /> The server sends a <code>remove</code> action where the directory to be removed is encoded as <code>version</code> parameter. The <code>newVersion</code> parameter is not set in the action. The client should delete the directory identified by the <code>version</code> parameter. A stored checksum entry for the directory in <code>version</code> should be removed, too, to reflect the changes.<br />
{<br />
"action" : "remove",<br />
"version" : {<br />
"path" : "/test1",<br />
"checksum" : "d41d8cd98f00b204e9800998ecf8427e"<br />
}<br />
}<br />
<br />
=== <code>sync</code> ===<br />
The client should trigger a synchronization of the files in the directory supplied in the <code>version</code> parameter using the <code>syncfiles</code> request. A <code>sync</code> action implies the client-side creation of the referenced directory if it not yet exists, in case of a new directory on the server. <br />
<br />
If the <code>version</code> parameter is not specified, a synchronization of all folders using the <code>syncfolders</code> request should be initiated by the client. <br />
<br />
If the <code>reset</code> flag in the <code>SYNC</code> action is set to <code>true</code>, the client should reset his local state before synchronizing the files in the directory. This may happen when the server detects a synchronization cycle, or believes something else is going wrong. Reset means that the client should invalidate any stored original checksums for the directory itself and any contained files, so that they get re-calculated upon the next synchronization. If the <code>reset</code> flag is set in a <code>SYNC</code> action without a apecific directory version, the client should invalidate any stored checksums, so that all file- and directory-versions get re-calculated during the following synchronizations. <br />
<br />
* Example 1: Synchronize folder <br /> The server sends a <code>sync</code> action with a <code>version</code>. The client should trigger a <code>syncfiles</code> request for the specified folder.<br />
{<br />
"action": "sync",<br />
"version": {<br />
"path": "<folder>",<br />
"checksum": "<md5>"<br />
}<br />
}<br />
<br />
* Example 2: Synchronize all folders <br /> The server sends a <code>sync</code> action without <code>version</code> (or version is //null//). The client should trigger a <code>syncfolder</code> request, i.e. the client should synchronize all folders.<br />
{<br />
"action": "sync",<br />
"version": null<br />
}<br />
<br />
=== <code>error</code> ===<br />
With the <code>error</code> action, file- or directory versions causing a synchronization problem can be identified. The root cause of the error is encoded in the <code>error</code> parameter as described at the [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (error handling)]. <br />
<br />
Basically, there are two scenarios where either the errorneous version affects the synchronization state or not. For example, a file that was deleted at the client without sufficient permissions on the server can just be downloaded again by the client, and afterwards, client and server are in-sync again. On the other hand, e.g. when creating a new file at the client and this file can't be uploaded to the server due to missing permissions, the client is out of sync as long as the file is present. Therefore, the boolean parameter <code>quarantine</code> instructs the client whether the file or directory version must be excluded from the synchronization or not. If it is set to <code>true</code>, the client should exclude the version from the <code>clientVersions</code> array, and indicate the issue to the enduser. However, if the synchronization itself is not affected and the <code>quarantine</code> flag is set to <code>false</code>, the client may still indicate the issue once to the user in the background, e.g. as a balloontip notification. <br />
<br />
The client may reset it's quarantined versions on it's own, e.g. if the user decides to "try again", or automatically after a configurable interval. <br />
<br />
The server may also decide that further synchronization should be suspended, e.g. in case of repeated synchronization problems. Such a situation is indicated with the parameter <code>stop</code> set to <code>true</code>. In this case, the client should at least cancel the current synchronization cycle. If appropriate, the client should also be put into a 'paused' mode, and the user should be informed accordingly. <br />
<br />
There may also be situations where a error or warning is sent to the client, independently of a file- or directory version, e.g. when the client version is outdated and a newer version is available for download.<br />
<br />
The most common examples for errors are insufficient permissions or exceeded quota restrictions, see examples below.<br />
<br />
* Example 1: Create a file in a read-only folder <br /> The server sends an <code>error</code> action where the errorneous file is encoded in the <code>newVersion</code> parameter and the <code>quarantine</code> flag is set to <code>true</code>. The client should exclude the version from the <code>clientVersions</code> array in upcoming <code>syncFiles</code> requests so that it doesn't affect the synchronization algorithm. The error message and further details are encoded in the <code>error</code> object of the action.<br />
{<br />
"error" : {<br />
"category" : 3,<br />
"error_params" : ["/test"],<br />
"error" : "You are not allowed to create files at \"/test\"",<br />
"error_id" : "1358320776-69",<br />
"categories" : "PERMISSION_DENIED",<br />
"code" : "DRV-0012"<br />
},<br />
"path" : "/test",<br />
"quarantine" : true,<br />
"action" : "error",<br />
"newVersion" : {<br />
"name" : "test.txt",<br />
"checksum" : "3f978a5a54cef77fa3a4d3fe9a7047d2"<br />
}<br />
}<br />
<br />
* Example 2: Delete a file without sufficient permissions <br /> Besides a new <code>download</code> action to restore the locally deleted file again, the server sends an <code>error</code> action where the errorneous file is encoded in the <code>version</code> parameter and the <code>quarantine</code> flag is set to <code>false</code>. Further synchronizations are not affected, but the client may still inform the user about the rejected operation. The error message and further details are encoded in the <code>error</code> object of the action.<br />
{<br />
"error" : {<br />
"category" : 3,<br />
"error_params" : ["test.png", "/test"],<br />
"error" : "You are not allowed to delete the file \"test.png\" at \"/test\"",<br />
"error_id" : "1358320776-74",<br />
"categories" : "PERMISSION_DENIED",<br />
"code" : "DRV-0011"<br />
},<br />
"path" : "/test",<br />
"quarantine" : false,<br />
"action" : "error",<br />
"newVersion" : {<br />
"name" : "test.png",<br />
"checksum" : "438f06398ce968afdbb7f4db425aff09"<br />
}<br />
}<br />
<br />
* Example 3: Upload a file that exceeds the quota <br /> The server sends an <code>error</code> action where the errorneous file is encoded in the <code>newVersion</code> parameter and the <code>quarantine</code> flag is set to <code>true</code>. The client should exclude the version from the <code>clientVersions</code> array in upcoming <code>syncFiles</code> requests so that it doesn't affect the synchronization algorithm. The error message and further details are encoded in the <code>error</code> object of the action.<br />
{<br />
"error" : {<br />
"category" : 3,<br />
"error_params" : [],<br />
"error" : "The allowed Quota is reached",<br />
"error_id" : "-485491844-918",<br />
"categories" : "PERMISSION_DENIED",<br />
"code" : "DRV-0016"<br />
},<br />
"path" : "/",<br />
"quarantine" : true,<br />
"action" : "error",<br />
"newVersion" : {<br />
"name" : "test.txt",<br />
"checksum" : "0ca6033e2a9c2bea1586a2984bf111e6"<br />
}<br />
}<br />
<br />
* Example 4: Synchronize with a client where the version is no longer supported. <br /> The server sends an <code>error</code> action with code <code>DRV-0028</code> and an appropriate error message. The <code>stop</code> flag is set to <code>true</code> to interrupt the synchronization cycle. <br />
{<br />
"stop" : true,<br />
"error" : {<br />
"category" : 13,<br />
"error_params" : [],<br />
"error" : "The client application you're using is outdated and no longer supported - please upgrade to a newer version.",<br />
"error_id" : "103394512-13",<br />
"categories" : "WARNING",<br />
"code" : "DRV-0028",<br />
"error_desc" : "Client outdated - current: \"0.9.2\", required: \"0.9.10\""<br />
},<br />
"quarantine" : false,<br />
"action" : "error"<br />
}<br />
<br />
* Example 5: Synchronize with a client where a new version of the client application is available. <br /> The server sends an <code>error</code> action with code <code>DRV-0029</code> and an appropriate error message. The <code>stop</code> flag is set to <code>false</code> to indicate that the synchronization can continue.<br />
{<br />
"stop" : false,<br />
"error" : {<br />
"category" : 13,<br />
"error_params" : [],<br />
"error" : "A newer version of your client application is available for download.",<br />
"error_id" : "103394512-29",<br />
"categories" : "WARNING",<br />
"code" : "DRV-0029",<br />
"error_desc" : "Client update available - current: \"0.9.10\", available: \"0.9.12\""<br />
},<br />
"quarantine" : false,<br />
"action" : "error"<br />
}<br />
<br />
== Synchronize folders ==<br />
<br />
This request performs the synchronization of all folders, resulting in different actions that should be executed on the client afterwards. This operation typically serves as an entry point for a synchronization cycle.<br />
<br />
PUT <code>/ajax/drive?action=syncfolders</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>version</code> - The current client version (matching the pattern <code>^[0-9]+(\\.[0-9]+)*$</code>). If not set, the initial version <code>0</code> is assumed.<br />
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.<br />
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.<br />
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.<br />
<br />
Request Body: <br /><br />
A JSON object containing two JSON arrays named <code>clientVersions</code> and <code>originalVersions</code>. The client versions array lists all current directories below the root directory as a flat list, encoded as [[#Directory_Version|Directory Versions]]. The original versions array contains all previously known directories, i.e. all previously synchronized and acknowledged directories, also encoded as [[#Directory_Version|Directory Versions]]. <br />
<br />
Optionally, available since API version 2, the JSON object may also contain two arrays named <code>fileExclusions</code> and <code>directoryExclusions</code> to define client-side exclusion filters, with each element encoded as [[#File_pattern|File patterns]] and [[#Directory_pattern|Directory patterns]] accordingly. See [[#Client_side_filtering|Client side filtering]] for details.<br />
<br />
Response: <br /><br />
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. <br /> If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=syncfolders&root=56&session=5d0c1e8eb0964a3095438b450ff6810f<br />
> Content:<br />
{<br />
"clientVersions" : [{<br />
"path" : "/",<br />
"checksum" : "7b744b13df4b41006495e1a15327368a"<br />
}, {<br />
"path" : "/test1",<br />
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"<br />
}, {<br />
"path" : "/test2",<br />
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"<br />
}, {<br />
"path" : "/test2/test3",<br />
"checksum" : "c193fae995d9f9431986dcdc3621cd98"<br />
}<br />
],<br />
"originalVersions" : [{<br />
"path" : "/",<br />
"checksum" : "7b744b13df4b41006495e1a15327368a"<br />
}, {<br />
"path" : "/test2/test3",<br />
"checksum" : "c193fae995d9f9431986dcdc3621cd98"<br />
}, {<br />
"path" : "/test2",<br />
"checksum" : "35d1b51fdefbee5bf81d7ae8167719b8"<br />
}, {<br />
"path" : "/test1",<br />
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"<br />
}<br />
]<br />
}<br />
<br />
<== HTTP 200 OK (8.0004 ms elapsed, 102 bytes received)<br />
< Content: <br />
{<br />
"data" : [{<br />
"action" : "sync",<br />
"version" : {<br />
"path" : "/test2",<br />
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"<br />
}<br />
}<br />
]<br />
}<br />
<br />
Example 2:<br />
==> PUT http://192.168.32.191/ajax/drive?action=syncfolders&root=56&session=5d0c1e8eb0964a3095438b450ff6810f<br />
> Content:<br />
{<br />
"clientVersions" : [{<br />
"path" : "/",<br />
"checksum" : "7b744b13df4b41006495e1a15327368a"<br />
}, {<br />
"path" : "/test1",<br />
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"<br />
}, {<br />
"path" : "/test2",<br />
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"<br />
}, {<br />
"path" : "/test2/test3",<br />
"checksum" : "c193fae995d9f9431986dcdc3621cd98"<br />
}<br />
],<br />
"originalVersions" : [{<br />
"path" : "/",<br />
"checksum" : "7b744b13df4b41006495e1a15327368a"<br />
}, {<br />
"path" : "/test2/test3",<br />
"checksum" : "c193fae995d9f9431986dcdc3621cd98"<br />
}, {<br />
"path" : "/test2",<br />
"checksum" : "35d1b51fdefbee5bf81d7ae8167719b8"<br />
}, {<br />
"path" : "/test1",<br />
"checksum" : "3ecc97334d7f6bf2b795988092b8137e"<br />
}<br />
]<br />
"fileExclusions" : [{<br />
"path" : "/",<br />
"name" : "excluded.txt",<br />
"type" : "exact"<br />
}<br />
], "directoryExclusions" : [{<br />
"path" : "/temp",<br />
"type" : "exact"<br />
}, {<br />
"path" : "/temp/*",<br />
"type" : "glob"<br />
}<br />
]<br />
}<br />
<br />
<== HTTP 200 OK (8.0004 ms elapsed, 102 bytes received)<br />
< Content: <br />
{<br />
"data" : [{<br />
"action" : "sync",<br />
"version" : {<br />
"path" : "/test2",<br />
"checksum" : "56534fc2ddcb3b7310d3ef889bc5ae18"<br />
}<br />
}<br />
]<br />
}<br />
<br />
<br />
== Synchronize files in a folder ==<br />
<br />
This request performs the synchronization of a single folder, resulting in different actions that should be executed on the client afterwards. This action is typically executed as result of a <code>syncfolders</code> action.<br />
<br />
PUT <code>/ajax/drive?action=syncfiles</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the synchronized folder, relative to the root folder.<br />
* <code>device</code> (optional) - A friendly name identifying the client device from a user's point of view, e.g. "My Tablet PC".<br />
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.<br />
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.<br />
* <code>columns</code> (optional) - A comma-separated list of columns representing additional metadata that is relevant for the client. Each column is specified by a numeric column identifier. Column identifiers for file metadata are defined in [[#FileMetadata|File Metadata]]. If available, the requested metadata of files is included in the corresponding <code>DOWNLOAD</code> and <code>ACKNOWLEDGE</code> actions (deprecated, available until API version 2).<br />
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.<br />
* <code>driveMeta</code> (optional, available since API version 5) - Controls the <code>.drive-meta</code> synchronization mode: <code>true</code>/<code>false</code> to forcibly enable or disable metadata synchronization for the request, or <code>inline</code> to include <code>.drive-meta</code>-data inside a corresponding <code>DOWNLOAD</code> action as <code>data</code>-parameter if suitable.<br />
<br />
Request Body: <br /><br />
A JSON object containing two JSON arrays named <code>clientVersions</code> and <code>originalVersions</code>. The client versions array lists all current files in the client directory, encoded as [[#File_Version | File Versions]]. The original versions array contains all previously known files, i.e. all previously synchronized and acknowledged files, also encoded as [[#File_Version | File Versions]]. <br />
<br />
Optionally, available since API version 2, the JSON object may also contain an array named <code>fileExclusions</code> to define client-side exclusion filters, with each element encoded as [[#File_pattern | File patterns]]. See [[#Client_side_filtering|Client side filtering]] for details.<br />
<br />
Response: <br /><br />
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. <br /> If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>. <br /> If <code>driveMeta</code> was set to <code>inline</code>, <code>DOWNLOAD</code> actions for <code>.drive-meta</code> will carry the metadata in an additional JSON object in the corresponding action's parameters at <code>data</code>, if the <code>.drive-meta</code>-file is smaller than a certain threshold (the contents may still be requested with an explicit download then).<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=56&path=/test2&device=Laptop&session=5d0c1e8eb0964a3095438b450ff6810f<br />
> Content: <br />
{<br />
"clientVersions" : [{<br />
"name" : "Jellyfish.jpg",<br />
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"<br />
}, {<br />
"name" : "Penguins.jpg",<br />
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"<br />
}<br />
],<br />
"originalVersions" : [{<br />
"name" : "Jellyfish.jpg",<br />
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"<br />
}<br />
]<br />
}<br />
<br />
<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)<br />
< Content:<br />
{<br />
"data" : [{<br />
"path" : "/test2",<br />
"action" : "upload",<br />
"newVersion" : {<br />
"name" : "Penguins.jpg",<br />
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"<br />
},<br />
"offset" : 0<br />
}<br />
]<br />
}<br />
<br />
Example 2:<br />
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=56&path=/test2&device=Laptop&session=5d0c1e8eb0964a3095438b450ff6810f<br />
> Content: <br />
{<br />
"clientVersions" : [{<br />
"name" : "Jellyfish.jpg",<br />
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"<br />
}, {<br />
"name" : "Penguins.jpg",<br />
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"<br />
}<br />
],<br />
"originalVersions" : [{<br />
"name" : "Jellyfish.jpg",<br />
"checksum" : "5a44c7ba5bbe4ec867233d67e4806848"<br />
}<br />
]<br />
"fileExclusions" : [{<br />
"path" : "*",<br />
"name" : "*.tmp",<br />
"type" : "glob"<br />
}<br />
]<br />
}<br />
<br />
<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)<br />
< Content:<br />
{<br />
"data" : [{<br />
"path" : "/test2",<br />
"action" : "upload",<br />
"newVersion" : {<br />
"name" : "Penguins.jpg",<br />
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"<br />
},<br />
"offset" : 0<br />
}<br />
]<br />
}<br />
<br />
Example 3:<br />
==> PUT http://192.168.32.191/ajax/drive?action=syncfiles&root=123975&path=/&apiVersion=4&driveMeta=inline&session=0833ca06093a4bad826347a30bf7ace7<br />
> Content: <br />
{<br />
"clientVersions": [],<br />
"originalVersions": []<br />
}<br />
<br />
<== HTTP 200 OK (27.5238 ms elapsed, 2058 bytes received)<br />
< Content:<br />
{<br />
"data": {<br />
"actions": [{<br />
"action": "download",<br />
"newVersion": {<br />
"checksum": "36301942a30c3c09bc59f6e9b0c63fba",<br />
"name": ".drive-meta"<br />
},<br />
"totalLength": 1511,<br />
"data": {<br />
"id": "123975",<br />
"own_rights": 403710016,<br />
"permissions": [{<br />
"bits": 403710016,<br />
"entity": 7,<br />
"group": false<br />
}],<br />
"extended_permissions": [{<br />
"entity": 7,<br />
"bits": 403710016,<br />
"type": "user",<br />
"display_name": "Test User 2",<br />
"contact": {<br />
"email1": "test2@local.ox",<br />
"last_name": "test2",<br />
"first_name": "test2"<br />
}<br />
}],<br />
"jump": ["permissions"],<br />
"shareable": true,<br />
"files": [{<br />
"name": "test1.txt",<br />
"created": 1460030191867,<br />
"modified": 1460030191867,<br />
"created_by": 7,<br />
"modified_by": 7,<br />
"content_type": "text/plain",<br />
"preview": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493515&version=1&delivery=download&scaleType=contain&width=1600&height=1600",<br />
"thumbnail": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493515&version=1&delivery=download&scaleType=contain&width=100&height=100",<br />
"shareable": true,<br />
"number_of_versions": 1,<br />
"version": "1",<br />
"jump": ["preview",<br />
"edit",<br />
"permissions",<br />
"version_history"]<br />
},<br />
{<br />
"name": "test2.txt",<br />
"created": 1460030191931,<br />
"modified": 1460030191931,<br />
"created_by": 7,<br />
"modified_by": 7,<br />
"content_type": "text/plain",<br />
"preview": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493516&version=1&delivery=download&scaleType=contain&width=1600&height=1600",<br />
"thumbnail": "http://local.ox/ajax/files?action=document&format=preview_image&folder=123975&id=123975/493516&version=1&delivery=download&scaleType=contain&width=100&height=100",<br />
"shareable": true,<br />
"number_of_versions": 1,<br />
"version": "1",<br />
"jump": ["preview",<br />
"edit",<br />
"permissions",<br />
"version_history"]<br />
}]<br />
},<br />
"path": "/",<br />
"modified": 1460030191779<br />
},<br />
{<br />
"action": "download",<br />
"newVersion": {<br />
"checksum": "e8d1be53d24895ae5cfc2808bec152bc",<br />
"name": "test1.txt"<br />
},<br />
"totalLength": 36,<br />
"created": 1460030191867,<br />
"path": "/",<br />
"modified": 1460030191867<br />
},<br />
{<br />
"action": "download",<br />
"newVersion": {<br />
"checksum": "767c4efab82482dcfafdcdbc034800d4",<br />
"name": "test2.txt"<br />
},<br />
"totalLength": 36,<br />
"created": 1460030191931,<br />
"path": "/",<br />
"modified": 1460030191931<br />
}]<br />
}<br />
}<br />
<br />
== Download a file ==<br />
<br />
Downloads a file from the server.<br />
<br />
GET <code>/ajax/drive?action=download</code><br />
<br />
or<br />
<br />
PUT <code>/ajax/drive?action=download</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the synchronized folder, relative to the root folder.<br />
* <code>name</code> - The name of the file version to download.<br />
* <code>checksum</code> - The checksum of the file version to download.<br />
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.<br />
* <code>offset</code> (optional) - The start offset in bytes for the download. If not defined, an offset of <code>0</code> is assumed.<br />
* <code>length</code> (optional) - The number of bytes to include in the download stream. If not defined, the file is read until the end.<br />
<br />
Request Body: <br /><br />
Optionally, available since API version 3, if client-side file- and/or directory exclusion filters are active, a PUT request can be used. The request body then holds a JSON object containing two arrays named <code>fileExclusions</code> and <code>directoryExclusions</code> to define client-side exclusion filters, with each element encoded as [[File_pattern|File patterns]] and [[Directory_pattern|Directory patterns]] accordingly. See [[Client_side_filtering|Client side filtering]] for details.<br />
<br />
Response: <br /><br />
The binary content of the requested file version. Note that in case of errors, an exception is not encoded in the default JSON error format here. Instead, an appropriate HTTP error with a status code != 200 is returned. For example, in case of the requested file being deleted or modified in the meantime, a response with HTTP status code 404 (not found) is sent.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=download&root=56&path=/test2&name=Jellyfish.jpg&checksum=5a44c7ba5bbe4ec867233d67e4806848&offset=0&length=-1&session=5d0c1e8eb0964a3095438b450ff6810f<br />
<br />
<== HTTP 200 OK (20.0011 ms elapsed, 775702 bytes received)<br />
<br />
== Upload a file ==<br />
<br />
Uploads a file to the server.<br />
<br />
PUT <code>/ajax/drive?action=upload</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the synchronized folder, relative to the root folder.<br />
* <code>newName</code> - The target name of the file version to upload.<br />
* <code>newChecksum</code> - The target checksum of the file version to upload.<br />
* <code>name</code> (optional) - The previous name of the file version being uploaded. Only set when uploading an updated version of an existing file to the server.<br />
* <code>checksum</code> - The previous checksum of the file version to upload. Only set when uploading an updated version of an existing file to the server.<br />
* <code>apiVersion</code> - The API version that the client is using. If not set, the initial version <code>0</code> is assumed.<br />
* <code>contentType</code> (optional) - The content type of the file. If not defined, <code>application/octet-stream</code> is assumed.<br />
* <code>offset</code> (optional) - The start offset in bytes for the upload when resuming a previous partial upload. If not defined, an offset of <code>0</code> is assumed.<br />
* <code>totalLength</code> (optional) - The total expected length of the file (required to support resume of uploads). If not defined, the upload is assumed completed after the operation.<br />
* <code>created</code> (optional) - The creation time of the file as timestamp.<br />
* <code>modified</code> (optional) - The last modification time of the file as timestamp. Defaults to the current server time if no value or a value larger than the current time is supplied.<br />
* <code>binary</code> - Expected to be set to <code>true</code> to indicate the binary content.<br />
* <code>device</code> (optional) - A friendly name identifying the client device from a user's point of view, e.g. "My Tablet PC".<br />
* <code>diagnostics</code> (optional) - If set to <code>true</code>, an additional diagnostics trace is supplied in the response.<br />
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.<br />
<br />
Request body: <br /><br />
The binary content of the uploaded file version. <br />
<br />
Response: <br /><br />
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. <br /> If the <code>diagnostics</code> flag was set (either to <code>true</code> or <code>false</code>), this array is wrapped into an additional JSON object in the <code>actions</code> parameter, and the diagnostics trace is provided at <code>diagnostics</code>.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=upload&root=56&path=/test2&newName=Penguins.jpg&newChecksum=9d377b10ce778c4938b3c7e2c63a229a&contentType=image/jpeg&offset=0&totalLength=777835&binary=true&device=Laptop&created=1375343426999&modified=1375343427001&session=5d0c1e8eb0964a3095438b450ff6810f<br />
> Content: <br />
[application/octet-stream;, 777835 bytes]<br />
<br />
<== HTTP 200 OK (108.0062 ms elapsed, 118 bytes received)<br />
< Content: <br />
{<br />
"data" : [{<br />
"action" : "acknowledge",<br />
"newVersion" : {<br />
"name" : "Penguins.jpg",<br />
"checksum" : "9d377b10ce778c4938b3c7e2c63a229a"<br />
}<br />
}<br />
]<br />
}<br />
<br />
== Listen for changes (long polling) ==<br />
<br />
Listens for server-side changes. The request blocks until new actions for the client are available, or an internal request timeout elapses. May return immediately if previously received but not yet processed actions are available for this client.<br />
<br />
GET <code>/ajax/drive?action=listen</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.<br />
<br />
Response: <br /><br />
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. If there are no changes were detected, an empty array is returned. Typically, the client will continue with the next <code>listen</code> request after the response was processed.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=listen&root=65841&session=51378e29f82042b4afe4af1c034c6d68<br />
<br />
<== HTTP 200 OK (63409.6268 ms elapsed, 28 bytes received)<br />
< Content: <br />
{<br />
"data" : [{<br />
"action" : "sync"<br />
}<br />
]<br />
}<br />
<br />
Alterantively, since API version 5, it's also possible to poll for changes in more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.<br />
<br />
PUT <code>/ajax/drive?action=listen</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>pushToken</code> (optional) - The client's push registration token to associate it to generated events.<br />
<br />
Request Body:<br />
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to listen for changes in.<br />
<br />
Response:<br /><br />
A JSON array containing all actions the client should execute for synchronization. Each array element is an action as described in [[#Actions | Actions]]. The relevant root folder identifier is available in the <code>root</code> parameter of the action. If there are no changes were detected, an empty array is returned. Typically, the client will continue with the next <code>listen</code> request after the response was processed.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=listen&session=51378e29f82042b4afe4af1c034c6d68<br />
> Content:<br />
{<br />
"root": [ "129136", "129137" ]<br />
},<br />
<br />
<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data" : [{<br />
"action" : "sync",<br />
"root" : "129137"<br />
}<br />
]<br />
}<br />
<br />
== Get quota ==<br />
<br />
Gets the quota limits and current usage for the storage the supplied root folder belongs to. Depending on the filestore configuration, this may include both restrictions on the number of allowed files and the total size of all contained files in bytes. If there's no limit, -1 is returned.<br />
<br />
GET <code>/ajax/drive?action=quota</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Response: <br /><br />
A JSON object containing the quota restrictions inside a JSON array with the property name <code>quota</code>. The JSON array contains zero, one or two <code>quota</code> objects as described below, depending on the filestore configuration. If one or more quota <code>type</code>s are missing in the array, the client can expect that there are no limitations for that type. Besides the array, the JSON object also contains a hyperlink behind the <code>manageLink</code> parameter, pointing to an URL where the user could manage his quota restrictions.<br />
<br />
{| id="Quota" cellspacing="0" border="1"<br />
|+ align="bottom" | Quota<br />
! Name !! Type !! Value<br />
|-<br />
| limit || Number || The allowed limit (either number of files or sum of filesizes in bytes).<br />
|-<br />
| use || Number || The current usage (again either number of files or sum of filesizes in bytes).<br />
|-<br />
| type || String || The kind of quota restriction, currently either <code>storage</code> (size of contained files in bytes) or <code>file</code> (number of files).<br />
|}<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=quota&root=56&session=35cb8c2d1423480692f0d5053d14ba52<br />
<br />
<== HTTP 200 OK (9.6854 ms elapsed, 113 bytes received)<br />
< Content: <br />
{<br />
"data" : {<br />
"quota" : [{<br />
"limit" : 107374182400,<br />
"use" : 1109974882,<br />
"type" : "storage"<br />
}, {<br />
"limit" : 800000000000,<br />
"use" : 1577,<br />
"type" : "file"<br />
}<br />
],<br />
"manageLink" : "https://www.example.com/manageQuota"<br />
}<br />
}<br />
<br />
== Get Settings ==<br />
<br />
Gets various settings applicable for the drive clients.<br />
<br />
GET <code>/ajax/drive?action=settings</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>language</code> (optional) - The locale to use for language-sensitive settings (in the format <code><2-letter-language>_<2-letter-region></code>, e.g. <code>de_CH</code> or <code>en_GB</code>). Defaults to the user's configured locale on the server.<br />
<br />
Response:<br /><br />
A JSON object holding the settings as described below. This also includes a JSON array with the property name <code>quota</code> that contains zero, one or two quota objects as described below, depending on the filestore configuration. If one or more quota types are missing in the array, the client can expect that there are no limitations for that type. <br />
<br />
{| id="Quota" cellspacing="0" border="1"<br />
|+ align="bottom" | Quota<br />
! Name !! Type !! Value<br />
|-<br />
| limit || Number || The allowed limit (either number of files or sum of filesizes in bytes).<br />
|-<br />
| use || Number || The current usage (again either number of files or sum of filesizes in bytes).<br />
|-<br />
| type || String || The kind of quota restriction, currently either <code>storage</code> (size of contained files in bytes) or <code>file</code> (number of files).<br />
|}<br />
<br />
{| id="Settings" cellspacing="0" border="1"<br />
|+ align="bottom" | Settings<br />
! Name !! Type !! Value<br />
|-<br />
| helpLink || String || A hyperlink to the online help.<br />
|-<br />
| quotaManageLink || String || A hyperlink to an URL where the user could manage his quota restrictions.<br />
|-<br />
| quota || Array || A JSON array containing the quota restrictions as described above.<br />
|-<br />
| serverVersion || String || The server version string.<br />
|-<br />
| supportedApiVersion || String || The API version supported by the server.<br />
|-<br />
| minApiVersion || String || The API version required to synchronize with the server.<br />
|-<br />
| localizedFolderNames || Object || A JSON object mapping the (relative) paths of directories to their localized name (based on the supplied <code>language</code> or the user's locale). Available with v7.8.1.<br />
|-<br />
| capabilities || Array || A JSON array holding relevant capabilities of the user. Available with v7.8.1.<br />
|}<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=settings&root=56&session=35cb8c2d1423480692f0d5053d14ba52<br />
<br />
<== HTTP 200 OK (11.3530 ms elapsed, 318 bytes received)<br />
< Content: <br />
{<br />
"data" : {<br />
"quota" : [{<br />
"limit" : 107374182400,<br />
"use" : 8828427,<br />
"type" : "storage"<br />
}, {<br />
"limit" : 800000000000,<br />
"use" : 1559,<br />
"type" : "file"<br />
}<br />
],<br />
"helpLink" : "http://192.168.32.191/appsuite/help-drive/l10n/de_DE/index.html",<br />
"quotaManageLink" : "http://192.168.32.191/manageQuota",<br />
"serverVersion" : "7.8.1-Rev1",<br />
"supportedApiVersion" : "4",<br />
"minApiVersion" : "1",<br />
"localizedFolderNames": {<br />
"/Documents": "Dokumente",<br />
"/Music": "Musik",<br />
"/Pictures": "Bilder",<br />
"/": "Meine Dateien",<br />
"/Documents/Templates": "Vorlagen"<br />
},<br />
"capabilities" : [<br />
"invite_guests",<br />
"share_links",<br />
"invite_users_and_groups"<br />
]<br />
}<br />
}<br />
<br />
== Subscribe to Push-Events ==<br />
<br />
Registers a client device to receive push notifications from the server. The subscription is performed based on the configured root folder ID of the client application that identifies itself with it's device token. Supported services currently include the Apple Push Notification Service (APN) and Google Cloud Messaging (GCM). Trying to perform an identical subscription (same <code>root</code>, <code>service</code> and <code>token</code>) from the same user account again is treated as a no-op.<br />
<br />
GET <code>/ajax/drive?action=subscribe</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.<br />
* <code>token</code> - The device's registration token as assigned by the service.<br />
<br />
Response:<br /><br />
An empty JSON result.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=subscribe&root=65841&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677<br />
<br />
<== HTTP 200 OK (13.6268 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data" : {<br />
}<br />
}<br />
<br />
Alterantively, since API version 5, a subscription can also be performed for more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.<br />
<br />
PUT <code>/ajax/drive?action=subscribe</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.<br />
* <code>token</code> - The device's registration token as assigned by the service.<br />
<br />
Request Body:<br />
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to subscribe to.<br />
<br />
Response:<br /><br />
An empty JSON result.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=subscribe&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677<br />
> Content:<br />
{<br />
"root": [ "129136", "129137" ]<br />
},<br />
<br />
<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data": {}<br />
}<br />
<br />
<br />
== Unsubscribe from Push-Events ==<br />
<br />
Unregisters a previously registered client device to stop receiving push notifications from the server. The same parameters that were used to perform the subscription need to be passed again, which includes the root folder ID, the device token and the service name.<br />
<br />
GET <code>/ajax/drive?action=unsubscribe</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.<br />
* <code>token</code> - The device's registration token as assigned by the service.<br />
<br />
Response:<br /><br />
An empty JSON result.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=unsubscribe&root=65841&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677<br />
<br />
<== HTTP 200 OK (26.0015 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data" : {<br />
}<br />
}<br />
<br />
Alterantively, since API version 5, an unsubscription can also be performed for more than one root folder, e.g. when also synchronizing a shared or public subfolder tree. Therefore, the <code>PUT</code> method can be used, with the root folder identifiers being passed in the request body.<br />
<br />
PUT <code>/ajax/drive?action=unsubscribe</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.<br />
* <code>token</code> - The device's registration token as assigned by the service.<br />
<br />
Request Body:<br />
A JSON object named <code>root</code> holding a JSON array of those root folder identifiers to unsubscribe from.<br />
<br />
Response:<br /><br />
An empty JSON result.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=unsubscribe&session=51378e29f82042b4afe4af1c034c6d68&service=apn&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677<br />
> Content:<br />
{<br />
"root": [ "129136", "129137" ]<br />
},<br />
<br />
<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data": {}<br />
}<br />
<br />
<br />
== Update the subscription token ==<br />
<br />
Updates a device's registration token in case a new one was assigned by the service.<br />
<br />
GET <code>/ajax/drive?action=updateToken</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>service</code> - The name of the underlying push service to use, currently one of <code>gcm</code>, <code>apn</code> or <code>apn.macos</code>.<br />
* <code>token</code> - The previous registration token as assigned by the service.<br />
* <code>newToken</code> - The new registration token as assigned by the service.<br />
<br />
Response:<br /><br />
An empty JSON result.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=updateToken&service=apn&session=51378e29f82042b4afe4af1c034c6d68&token=28919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677&newToken=38919862989a1b5ba59c11d5f7cb7ba2b9678be9dd18b033184d04f682013677<br />
<br />
<== HTTP 200 OK (15.6653 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data" : {<br />
}<br />
}<br />
<br />
== Get file metadata ==<br />
<br />
Deprecated, available until API version 2. <br /><br />
Additional metadata of synchronized files is made available via the <code>fileMetadata</code> request.<br />
<br />
PUT <code>/ajax/drive?action=fileMetata</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the synchronized folder, relative to the root 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 file metadata are defined in [[#FileMetadata|File Metadata]].<br />
<br />
Request Body:<br /><br />
A JSON array containing the file versions to get the metadata for. Each object in the array should be sent as [[#File_Version | File Versions]], and needs to be present in the referenced path.<br />
<br />
Response:<br /><br />
A JSON array containing the file metadata in the order of the requested file versions. Each array element describes one file metadata 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="FileMetadataDeprecated" cellspacing="0" border="1"<br />
|+ align="bottom" | File Metadata (deprecated)<br />
! ID !! Name !! Type !! Value<br />
|-<br />
| name || String || The name of the file version. <br />
|-<br />
| 4 || created || Timestamp || The file's last modification time (always UTC, not translated into user time). <br />
|-<br />
| 5 || modified || Timestamp || The file's last modification time (always UTC, not translated into user time). <br />
|-<br />
| 702 || name || String || The name of the file, including it's extension, e.g. <code>test.doc</code>. <br />
|-<br />
| 703 || contentType || String || The file's content type, e.g. "image/png". <br />
|-<br />
| 708 || checksum || String || The MD5 hash of the file, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>. <br />
|-<br />
| 750 || previewLink || String || A direct link to a medium-sized preview image of the file if available. <br />
|-<br />
| 751 || directLinkFragments || String | The fragments part of the direct link that can be used in combination with the [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (token login)] method to jump directly to the detail view of the file in the web interface, bypassing the need to login manually. <br />
|-<br />
| 752 || directLink || String || A direct link to the detail view of the file in the web interface. <br />
|-<br />
| 753 || thumbnailLink || String || A direct link to a small thumbnail image of the file if available. <br />
|}<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=fileMetadata&root=97974&path=%2f&columns=702%2c708%2c752%2c750%2c753&session=43aca91a80de42559ff0c2493dd973d0<br />
> Content:<br />
[<br />
{<br />
"name" : "image.jpg",<br />
"checksum" : "2b04df3ecc1d94afddff082d139c6f15"<br />
}, {<br />
"name" : "song.mp3",<br />
"checksum" : "5a9a91184e611dae3fed162b8787ce5f"<br />
}, {<br />
"name" : "test1.txt",<br />
"checksum" : "7e36f409a042f06ecb88606a97a88c8f"<br />
}, {<br />
"name" : "test3.txt",<br />
"checksum" : "703bc9aabff33faf07cf121dcda12ec8"<br />
}<br />
] <br />
<br />
<== HTTP 200 OK (6.0004 ms elapsed, 140 bytes received)<br />
< Content:<br />
[<br />
["image.jpg", "2b04df3ecc1d94afddff082d139c6f15", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179629", "https://192.168.32.191/ajax/files?action=document&folder=97974&id=179629&version=1&delivery=download&scaleType=contain&width=128&height=90", "m=infostore&f=97974&i=179629"], <br />
["song.mp3", "5a9a91184e611dae3fed162b8787ce5f", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179630", "https://192.168.32.191/ajax/image/file/mp3Cover?folder=97974&id=179630&version=1&delivery=download&scaleType=contain&width=128&height=90", "m=infostore&f=97974&i=179630"], <br />
["test1.txt", "7e36f409a042f06ecb88606a97a88c8f", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179626", null, "m=infostore&f=97974&i=179626"], <br />
["test3.txt", "703bc9aabff33faf07cf121dcda12ec8", "https://192.168.32.191/ox6/index.html#m=infostore&f=97974&i=179624", null, "m=infostore&f=97974&i=179624"]<br />
]<br />
<br />
== Get a direct link for a folder/a file into appsuite ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Generate a direct link into appsuite UI for a synchronized file/a synchronized folder and a token for token-based login.<br />
<br />
POST <code>/ajax/drive?action=jump</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the synchronized folder, relative to the root folder.<br />
* <code>name</code> - The name of the file in the synchronized folder given in <code>path</code>-parameter. Optional<br />
* <code>method</code> - [[#Methods | Methods]]<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>clientToken</code> - Client side identifier for accessing the session later. The value should be some token that is unique for every login request.<br />
<br />
Methods:<br /><br />
* <code>edit</code>: Open the file in appsuite editor or in text/spreadsheet (if available).<br />
* <code>permissions</code>: Open the file's/folder's change-permission dialog.<br />
* <code>version_history</code>: Open the file's version history summary.<br />
* <code>preview</code>: Open the file's/folder's preview.<br />
<br />
Response:<br /><br />
A JSON array containing the direct link to the file/folder including a server token for token based login.<br />
<br />
Example:<br />
==> POST http://localhost/ajax/drive?action=jump&session=48a289898ad949faaa46c04e7fb422f5&root=9547&path=/path/to/file&name=file_to_edit.txt&method=edit&authId=41763584-8460-11e4-b116-123b93f75dba<br />
> Content: clientToken=47d74b1c-81df-11e4-b116-123b93f75cba<br />
<br />
<== HTTP 200 OK<br />
< Content: <br />
{<br />
"data": {<br />
"redirectUrl": "http://localhost/appsuite#app=io.ox/editor&folder=273264&id=273264/307438&serverToken=7b90972628e34e89bb9a3946d1372c68"<br />
}<br />
}<br />
<br />
== Use direct link and token with token-based login ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Login to appsuite UI with token-based login via the link created with [[#Get a direct link for a folder/a file into appsuite | Get a direct link for a folder/a file into appsuite]].<br />
<br />
GET <code>[direct link]</code><br />
<br />
Parameters:<br />
* <code>clientToken</code> – Client side identifier for accessing the session. The value must be the same as in [[#Get a direct link for a folder/a file into appsuite | Get a direct link for a folder/a file into appsuite]].<br />
<br />
Example:<br />
==> GET http://localhost/appsuite#app=io.ox/editor&folder=273264&id=273264/307438&serverToken=7b90972628e34e89bb9a3946d1372c68&clientToken=47d74b1c-81df-11e4-b116-123b93f75cba<br />
<br />
<== HTTP 200 OK<br />
<br />
== Get synchronizable Folders ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Allows getting a list of folders that are available on the server for synchronization. This request should be used to build up a folder tree and let the user select the root synchronization folder(s). <br />
<br />
GET <code>/ajax/drive?action=subfolders</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>parent</code> - The ID of the parent folder to get the subfolders for as read from a previously fetched directory metadata object. Optional; if not set, the root available root folders are returned.<br />
<br />
Response:<br /><br />
A JSON array holding metadata information for all subfolders as defined in [[#DirectoryMetadata | Directory Metadata]], with the <code>files</code> array being left out. <br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=subfolders&session=35cb8c2d1423480692f0d5053d14ba52<br />
<br />
<== HTTP 200 OK (241.0252 ms elapsed, 966 bytes received)<br />
< Content: <br />
{<br />
"data": [{<br />
"id": "com.openexchange.file.storage.googledrive://1/",<br />
"name": "Google Drive",<br />
"path": "/Google Drive",<br />
"has_subfolders": true,<br />
"own_rights": 403710016,<br />
"permissions": [{<br />
"bits": 403710016,<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
}],<br />
"jump": ["permissions"]<br />
},<br />
{<br />
"id": "10",<br />
"name": "Freigegebene Dateien",<br />
"path": "/Freigegebene Dateien",<br />
"created": 1224493261628,<br />
"modified": 1417164170136,<br />
"has_subfolders": true,<br />
"own_rights": 1,<br />
"permissions": [{<br />
"bits": 1,<br />
"group": true,<br />
"entity": 0,<br />
"display_name": "All users",<br />
"guest": false<br />
},<br />
{<br />
"bits": 1,<br />
"group": true,<br />
"entity": 2147483647,<br />
"display_name": "Guests",<br />
"guest": false<br />
}],<br />
"jump": ["permissions"],<br />
"shared": true<br />
},<br />
{<br />
"id": "15",<br />
"name": "Öffentliche Dateien",<br />
"path": "/Öffentliche Dateien",<br />
"created": 1224493261628,<br />
"modified": 1418383637250,<br />
"has_subfolders": true,<br />
"own_rights": 403709956,<br />
"permissions": [{<br />
"bits": 403709956,<br />
"group": true,<br />
"entity": 0,<br />
"display_name": "All users",<br />
"guest": false<br />
},<br />
{<br />
"bits": 1,<br />
"group": true,<br />
"entity": 2147483647,<br />
"display_name": "Guests",<br />
"guest": false<br />
}],<br />
"jump": ["permissions"],<br />
"shared": true<br />
},<br />
{<br />
"id": "com.openexchange.file.storage.dropbox://1/",<br />
"name": "Dropbox",<br />
"path": "/Dropbox",<br />
"has_subfolders": true,<br />
"own_rights": 403710016,<br />
"permissions": [{<br />
"bits": 403710016,<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
}],<br />
"jump": ["permissions"]<br />
},<br />
{<br />
"id": "9542",<br />
"name": "Meine Dateien",<br />
"path": "/Meine Dateien",<br />
"created": 1320230546147,<br />
"modified": 1426764458823,<br />
"default_folder": true,<br />
"has_subfolders": true,<br />
"own_rights": 403710016,<br />
"permissions": [{<br />
"bits": 403710016,<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
}],<br />
"jump": ["permissions"]<br />
}]<br />
}<br />
<br />
== Get a share link ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Creates a new or gets the previously created link for a file or folder that can be used to access the item in a browser by anyone. This action is only available for items marked as <code>shareable</code>.<br />
<br />
PUT <code>/ajax/drive?action=getLink</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Request body:<br /><br />
A JSON object describing the target file- or directory version to get the link for as described in [[#DriveShareTarget|Drive Share Target]].<br />
<br />
Response:<br /><br />
A JSON object containing details about the share link, including its URL, as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (share link)]. Additionally, the current checksum of the share target is included (starting with v7.8.1).<br />
<br />
{| id="DriveShareTarget" cellspacing="0" border="1"<br />
|+ align="bottom" | Drive Share Target<br />
! Name !! Type !! Value<br />
|-<br />
| name || String || (Optional) The name of the file, including its extension, e.g. <code>test.doc</code>. Not set if the target is a directory.<br />
|-<br />
| path || String || The path of the (file's parent) directory, relative to the root folder.<br />
|-<br />
| checksum || String || The MD5 hash of the file or directory, expressed as a lowercase hexadecimal number string, 32 characters long, e.g. <code>f8cacac95379527cd4fa15f0cb782a09</code>.<br />
|}<br />
<br />
Example 1: Get the intial link for a file<br />
==> PUT http://192.168.32.191/ajax/drive?action=getLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
> Content:<br />
{<br />
"path": "/",<br />
"name": "photo.jpg",<br />
"checksum": "bdf3bf1da3405725be763540d6601144"<br />
}<br />
<br />
<== HTTP 200 OK (311.8978 ms elapsed, 118 bytes received)<br />
< Content: <br />
{<br />
"data": {<br />
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",<br />
"is_new": true,<br />
"checksum": "bdf3bf1da3405725be763540d6601144"<br />
}<br />
}<br />
<br />
Example 2: Get an already existing link for a file<br />
==> PUT http://192.168.32.191/ajax/drive?action=getLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
> Content:<br />
{<br />
"path": "/",<br />
"name": "photo.jpg",<br />
"checksum": "bdf3bf1da3405725be763540d6601144"<br />
}<br />
<br />
<== HTTP 200 OK (78.0547 ms elapsed, 167 bytes received)<br />
< Content: <br />
{<br />
"data": {<br />
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",<br />
"is_new": false,<br />
"expiry_date": 1451606400000,<br />
"password": "secret",<br />
"checksum": "bdf3bf1da3405725be763540d6601144"<br />
}<br />
}<br />
<br />
== Update a share link ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Updates a previously created link for a file or folder. This action is only available for items marked as <code>shareable</code>.<br />
<br />
PUT <code>/ajax/drive?action=updateLink</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Request Body:<br /><br />
A JSON object as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (share link)] containing the properties of the link to update, as well as the share target itself as described in [[#DriveShareTarget|Drive Share Target]]. Only modified fields should be set.<br />
<br />
Response:<br /><br />
A JSON object containing details about the share link, including its URL, as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (share link)]. Additionally, the current checksum of the share target is included (starting with v7.8.1).<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=updateLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
> Content:<br />
{<br />
"path": "/",<br />
"name": "photo.jpg",<br />
"checksum": "bdf3bf1da3405725be763540d6601144",<br />
"password": "secret",<br />
"expiry_date": 1451606400000<br />
}<br />
<br />
<== HTTP 200 OK (341.8978 ms elapsed, 218 bytes received)<br />
< Content: <br />
{<br />
"data": {<br />
"url": "http://127.0.0.1/ajax/share/17bc4ac00d424e85ef5272dd427342438e7f20b415aba46c/4df04226",<br />
"is_new": false,<br />
"checksum": "bdf3bf1da3405725be763540d6601144",<br />
"password": "secret",<br />
"expiry_date": 1451606400000<br />
}<br />
}<br />
<br />
== Delete a share link ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Deletes a previously created link for a file or folder. This action is only available for items marked as <code>shareable</code>.<br />
<br />
PUT <code>/ajax/drive?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Request body:<br /><br />
A JSON object describing the target file- or directory version to delete the link for as described in [[#DriveShareTarget|Drive Share Target]].<br />
<br />
Response:<br /><br />
An empty JSON object.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=deleteLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
> Content:<br />
{<br />
"path": "/",<br />
"name": "photo.jpg",<br />
"checksum": "bdf3bf1da3405725be763540d6601144"<br />
}<br />
<br />
<== HTTP 200 OK (149.3251 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data": {}<br />
}<br />
<br />
== Send a share link ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Sends a notification message for a share link to one or more recipients.<br />
<br />
PUT <code>/ajax/drive?action=sendLink</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Request body:<br /><br />
A JSON object describing the target file- or directory version to send the link for as described in [[#DriveShareTarget|Drive 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. Optionally, a custom notification message may be specified in a <code>message</code> property (otherwise, some default message is used). <br />
<br />
Response:<br /><br />
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=sendLink&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
> Content:<br />
{<br />
"path": "/",<br />
"name": "photo.jpg",<br />
"checksum": "bdf3bf1da3405725be763540d6601144",<br />
"recipients": [<br />
["Otto Example", "otto@example.com"],<br />
["Horst Example", "horst@example.org"]<br />
] <br />
}<br />
<br />
<== HTTP 200 OK (260.9242 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data": {}<br />
}<br />
<br />
== Get shares ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Gets all files and directories within the synchronized tree that are shared to others.<br />
<br />
GET <code>/ajax/drive?action=shares</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Response:<br /><br />
The metadata of the shared items as a JSON object holding two JSON arrays <code>files</code> and <code>directories</code> containing the metadata as defined in [[#FileMetadata|File Metadata]] and [[#Directory_Metadata|DirectoryMetadata]] respectively.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=shares&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
<br />
<== HTTP 200 OK (191.2707 ms elapsed, 5339 bytes received)<br />
< Content: <br />
{<br />
"data": {<br />
"directories": [{<br />
"id": "316770",<br />
"name": "test",<br />
"checksum": "bef03e92c3c675c1a6efddc831ac21b9",<br />
"localized_name": "test",<br />
"path": "/test",<br />
"created": 1437989289761,<br />
"modified": 1438176370780,<br />
"own_rights": 403710016,<br />
"permissions": [{<br />
"bits": 403710016,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"type": "user"<br />
},<br />
{<br />
"bits": 135274497,<br />
"entity": 8340,<br />
"display_name": "Otto Example",<br />
"email_address": "otto@example.com",<br />
"type": "guest"<br />
},<br />
{<br />
"bits": 257,<br />
"entity": 16175,<br />
"display_name": "Guest",<br />
"type": "anonymous"<br />
}],<br />
"extended_permissions": [{<br />
"entity": 182,<br />
"bits": 403710016,<br />
"type": "user",<br />
"display_name": "Mander, Jens",<br />
"contact": {<br />
"email1": "jens.mander@example.com",<br />
"last_name": "Mander",<br />
"first_name": "Jens"<br />
}<br />
},<br />
{<br />
"entity": 8340,<br />
"bits": 135274497,<br />
"type": "guest",<br />
"display_name": "Otto Example",<br />
"contact": {<br />
"email1": "otto@example.com"<br />
}<br />
},<br />
{<br />
"entity": 16175,<br />
"bits": 257,<br />
"type": "anonymous",<br />
"share_url": "http://127.0.0.1/ajax/share/102b560404b3e96c9623be94b3d643829a46b117558d9ec9/31342f1f"<br />
}],<br />
"jump": ["permissions"],<br />
"shared": true,<br />
"shareable": true<br />
},<br />
{<br />
"id": "300695",<br />
"name": "sharetest",<br />
"checksum": "cdfb5724f9614290a850ec507aea72a2",<br />
"localized_name": "sharetest",<br />
"path": "/sub1/check/sharetest",<br />
"created": 1430218822598,<br />
"modified": 1430218833769,<br />
"own_rights": 403710016,<br />
"permissions": [{<br />
"bits": 257,<br />
"entity": 10,<br />
"display_name": "Klaus Mander",<br />
"email_address": "klaus.mander@example.com",<br />
"type": "user"<br />
},<br />
{<br />
"bits": 403710016,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"type": "user"<br />
}],<br />
"extended_permissions": [{<br />
"entity": 10,<br />
"bits": 257,<br />
"type": "user",<br />
"display_name": "Klaus Mander",<br />
"contact": {<br />
"email1": "klaus.mander@example.com",<br />
"title": "",<br />
"last_name": "Mander",<br />
"first_name": "Klaus",<br />
"image1_url": "/ajax/image/user/picture?id=10&timestamp=1413376661353"<br />
}<br />
},<br />
{<br />
"entity": 182,<br />
"bits": 403710016,<br />
"type": "user",<br />
"display_name": "Mander, Jens",<br />
"contact": {<br />
"email1": "jens.mander@example.com",<br />
"last_name": "Mander",<br />
"first_name": "Jens"<br />
}<br />
}],<br />
"jump": ["permissions"],<br />
"shared": true,<br />
"shareable": true<br />
}],<br />
"files": [{<br />
"name": "Chrysanthemum.jpg",<br />
"created": 1438177192835,<br />
"modified": 1438177729597,<br />
"created_by": {<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"type": "user"<br />
},<br />
"modified_by": {<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"type": "user"<br />
},<br />
"preview": "http://127.0.0.1/ajax/files?action=document&folder=309373&id=309373/346541&version=1&delivery=download&scaleType=contain&width=800&height=800&rotate=true",<br />
"thumbnail": "http://127.0.0.1/ajax/files?action=document&folder=309373&id=309373/346541&version=1&delivery=download&scaleType=contain&width=100&height=100&rotate=true",<br />
"object_permissions": [{<br />
"bits": 1,<br />
"entity": 16178,<br />
"display_name": "Guest",<br />
"type": "anonymous"<br />
}],<br />
"extended_object_permissions": [{<br />
"entity": 16178,<br />
"bits": 1,<br />
"type": "anonymous",<br />
"share_url": "http://127.0.0.1/ajax/share/1224dd0b065f2076b6db0e665f1f441f89f1308ad2a8ad7f/167e4881"<br />
}],<br />
"shared": true,<br />
"shareable": true,<br />
"jump": ["preview",<br />
"permissions"],<br />
"path": "/Pictures",<br />
"checksum": "076e3caed758a1c18c91a0e9cae3368f"<br />
},<br />
{<br />
"name": "data.zip",<br />
"created": 1427291138800,<br />
"modified": 1438593586254,<br />
"created_by": {<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"type": "user"<br />
},<br />
"modified_by": {<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"type": "user"<br />
},<br />
"object_permissions": [{<br />
"bits": 4,<br />
"entity": 10,<br />
"display_name": "Klaus Mander",<br />
"email_address": "klaus.mander@example.com",<br />
"type": "user"<br />
},<br />
{<br />
"bits": 4,<br />
"entity": 8338,<br />
"display_name": "Horst Example",<br />
"email_address": "horst@example.com",<br />
"type": "guest"<br />
},<br />
{<br />
"bits": 1,<br />
"entity": 11224,<br />
"display_name": "Guest",<br />
"type": "anonymous"<br />
}],<br />
"extended_object_permissions": [{<br />
"entity": 10,<br />
"bits": 4,<br />
"type": "user",<br />
"display_name": "Klaus Mander",<br />
"contact": {<br />
"email1": "klaus.mander@example.com",<br />
"title": "",<br />
"last_name": "Mander",<br />
"first_name": "Klaus",<br />
"image1_url": "/ajax/image/user/picture?id=10&timestamp=1413376661353"<br />
}<br />
},<br />
{<br />
"entity": 8338,<br />
"bits": 4,<br />
"type": "guest",<br />
"display_name": "Horst Example",<br />
"contact": {<br />
"email1": "horst@example.com"<br />
}<br />
},<br />
{<br />
"entity": 11224,<br />
"bits": 1,<br />
"type": "anonymous",<br />
"share_url": "http://127.0.0.1/ajax/share/1f74962e0b55529663dfbc3b55794ea59b753c9301c0da75/76c846ae"<br />
}],<br />
"shared": true,<br />
"shareable": true,<br />
"jump": ["permissions"],<br />
"path": "/Projects/ACME",<br />
"checksum": "d63540e8f986ec305b0dd1293d8a3276"<br />
}]<br />
}<br />
}<br />
<br />
<br />
== Get directory metadata ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Gets metadata of a specific synchronized directory. <br />
<br />
GET <code>/ajax/drive?action=getFolder</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the directory to update, relative to the root folder.<br />
* <code>checksum</code> - The checksum of the directory to update.<br />
<br />
Response:<br /><br />
A JSON object representing the requested directoy metadata as described in [[#DirectoryMetadata|Directory Metadata]].<br />
<br />
== Get file metadata ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Gets metadata of a specific synchronized file. <br />
<br />
PUT <code>/ajax/drive?action=getFile</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the synchronized folder, relative to the root folder.<br />
* <code>name</code> - The name of the file version to update.<br />
* <code>checksum</code> - The checksum of the file version to update.<br />
<br />
Response:<br /><br />
A JSON object representing the requested directory metadata as described in [[#FileMetadata|File Metadata]].<br />
<br />
<br />
== Update directory metadata ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Updates specific metadata of a synchronized directory. This currently only includes the permissions - which in turn is only allowed for folders marked as <code>shareable</code>. <br />
<br />
PUT <code>/ajax/drive?action=updateFolder</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the directory to update, relative to the root folder.<br />
* <code>checksum</code> - The checksum of the directory to update.<br />
<br />
Request body:<br /><br />
A JSON object named <code>folder</code> describing the updated folder metadata as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Detailed Folder Data)]. Currently, only the property <code>permissions</code> is considered. To notify added permission entities, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed. To notify without a custom message, an empty <code>notification</code> object should still be added.<br />
<br />
Response:<br /><br />
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=updateFolder&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542&path=/test&checksum=d41d8cd98f00b204e9800998ecf8427e<br />
> Content:<br />
{<br />
"folder": {<br />
"permissions": [{<br />
"group": false,<br />
"bits": 403710016,<br />
"entity": 182<br />
},<br />
{<br />
"type": "guest",<br />
"email_address": "otto@example.com",<br />
"display_name": "Otto Example",<br />
"bits": 135274497<br />
}]<br />
},<br />
"notification": {<br />
"message": "Look!"<br />
}<br />
}<br />
<br />
<== HTTP 200 OK (207.1722 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data": {}<br />
}<br />
<br />
== Update file metadata ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
Updates specific metadata of a synchronized file. This currently only includes the object permissions - which in turn is only allowed for files marked as <code>shareable</code>. <br />
<br />
PUT <code>/ajax/drive?action=updateFile</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
* <code>path</code> - The path to the synchronized folder, relative to the root folder.<br />
* <code>name</code> - The name of the file version to update.<br />
* <code>checksum</code> - The checksum of the file version to update.<br />
<br />
Request body:<br /><br />
A JSON object named <code>file</code> describing the updated file metadata as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Detailed Infoitem Data)]. Currently, only the property <code>object_permissions</code> is considered. To notify added permission entities, an additional JSON object <code>notification</code> may be included, inside of which an optional <code>message</code> can be passed. To notify without a custom message, an empty <code>notification</code> object should still be added.<br />
<br />
Response:<br /><br />
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=updateFolder&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542&path=/test&checksum=d41d8cd98f00b204e9800998ecf8427e<br />
> Content:<br />
{<br />
"file": {<br />
"object_permissions": [{<br />
"type": "guest",<br />
"email_address": "otto@example.com",<br />
"display_name": "Otto Example",<br />
"bits": 16641<br />
}]<br />
},<br />
"notification": {<br />
"message": "Look!"<br />
}<br />
}<br />
<br />
<== HTTP 200 OK (132.7421 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data": {}<br />
}<br />
<br />
== Notify about shared items ==<br />
<br />
Available since API version 4. <br /> <br />
<br />
(Re-)Sends a share notification to one or more permission entities of a specific shared file or folder. <br />
<br />
PUT <code>/ajax/drive?action=notify</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Request body:<br /><br />
A JSON object describing the target file- or directory version to send the notification for as described in [[#DriveShareTarget|Drive Share Target]]. The entity IDs of the recipients are listed in the JSON array named <code>entities</code>. Optionally, an additional JSON object <code>notification</code> may be included, inside of which a custom <code>message</code> can be passed (otherwise, some default message is used).<br />
<br />
Response:<br /><br />
An empty JSON object. Any transport warnings that occurred during sending the notifications are available in the <code>warnings</code> array of the response.<br />
<br />
Example:<br />
==> PUT http://192.168.32.191/ajax/drive?action=notify&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
> Content:<br />
{<br />
"path": "/test",<br />
"name": "image.jpg",<br />
"checksum": "d63540e8f986ec305b0dd1293d8a3276",<br />
"entities": [10,78],<br />
"notification": {<br />
"message": "Look!"<br />
}<br />
}<br />
<br />
<== HTTP 200 OK (45.2084 ms elapsed, 11 bytes received)<br />
< Content: <br />
{<br />
"data": {}<br />
}<br />
<br />
== Get trash folder statistics ==<br />
<br />
Available since API version 5. <br /> <br />
<br />
Gets statistics about the trash folder contents. <br /> <br />
If a trash folder is available or not can be checked via <code>hasTrashFolder</code> received in the [[#Get Settings | Settings]] request.<br />
<br />
GET <code>/ajax/drive?action=trashStats</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Response:<br /><br />
A JSON object holding the recursively accumulated folder statistics as described in [[#FolderStats|Folder Statistics]] below. If no trash folder is available, an empty response is returned.<br />
<br />
{| id="FolderStats" cellspacing="0" border="1"<br />
|+ align="bottom" | Folder Statistics<br />
! Name !! Type !! Value<br />
|-<br />
| totalSize || Number || The total size of the contents in bytes.<br />
|-<br />
| numFiles || Number || The total number of contained files.<br />
|-<br />
| numFolders || Number || The total number of contained folders.<br />
|}<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=trashStats&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
<br />
<== HTTP 200 OK (64.2423 ms elapsed, 67 bytes received)<br />
< Content: <br />
{<br />
"data": {<br />
"totalSize": 30904580,<br />
"numFiles": 39,<br />
"numFolders": 4<br />
}<br />
}<br />
<br />
== Empty trash folder ==<br />
<br />
Available since API version 5. <br /> <br />
<br />
Empties the trash folder, i.e. permanently removes any contained files and folders. <br /> <br />
If a trash folder is available or not can be checked via <code>hasTrashFolder</code> received in the [[#Get Settings | Settings]] request.<br />
<br />
GET <code>/ajax/drive?action=emptyTrash</code><br />
<br />
Parameters:<br />
* <code>session</code> - A session ID previously obtained from the login module.<br />
* <code>root</code> - The ID of the referenced root folder on the server.<br />
<br />
Response:<br /><br />
A JSON object holding the updated folder statistics after the trash was emptied as described in [[#FolderStats|Folder Statistics]]. If no trash folder is available, an empty response is returned.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=emptyTrash&session=35d55f0bd2284e78a8eb4dba99b1310b&root=9542<br />
<br />
<== HTTP 200 OK (184.0234 ms elapsed, 52 bytes received)<br />
< Content: <br />
{<br />
"data": {<br />
"totalSize": 0,<br />
"numFiles": 0,<br />
"numFolders": 0<br />
}<br />
}<br />
<br />
== Autocomplete contacts ==<br />
<br />
Available since API version 5. <br /> <br />
<br />
Performs a "starts-with" search to find users, contacts and groups, e.g. to look up recipients when sharing a folder or item. <br /> <br />
Prior triggering the request, clients should check the user input against the configured value of <code>minSearchChars</code> received in the [[#Get Settings | Settings]] request.<br />
<br />
GET <code>/ajax/drive?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 (no need to include additional wildcards).<br />
<br />
Response:<br /><br />
A JSON array holding the found users, contacts and groups. Each element is an object as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Extended Permission Object)], without the "bits" property set. For external contacts, the fields "entity" and "type" are also not set.<br />
<br />
Example:<br />
==> GET http://192.168.32.191/ajax/drive?action=autocomplete&query=tes&session=35d55f0bd2284e78a8eb4dba99b1310b<br />
<br />
<== HTTP 200 OK (184.0234 ms elapsed, 52 bytes received)<br />
< Content: <br />
{<br />
"data": [{<br />
"contact": {<br />
"email1": "test1@local.ox",<br />
"last_name": "test1",<br />
"first_name": "test1"<br />
},<br />
"display_name": "Test User 1",<br />
"type": "user",<br />
"entity": 6<br />
},<br />
{<br />
"contact": {<br />
"email1": "test4@local.ox",<br />
"last_name": "test4",<br />
"first_name": "test4",<br />
"image1_url": "/ajax/image/user/picture?id=13&timestamp=1453973021020"<br />
},<br />
"display_name": "Test User 4",<br />
"type": "user",<br />
"entity": 13<br />
},<br />
{<br />
"contact": {<br />
"email1": "test@example.org",<br />
"last_name": "Test",<br />
"first_name": "Otto",<br />
"image1_url": "/ajax/image/contact/picture?folder=31&id=118493&timestamp=1465481052986"<br />
},<br />
"display_name": "Test, Otto"<br />
},<br />
{<br />
"entity": 3851,<br />
"type": "group",<br />
"display_name": "Test Group"<br />
}]<br />
}<br />
<br />
<br />
= File- and Directory Name Restrictions =<br />
<br />
Regarding the case sensitivity of file and directory names, OX Drive works in a case-insensitive, but case-preserving way. That means that there cannot be two files with an equal name ignoring case in the same directory, but it's still possible to synchronize the names in a case-sensitive manner, as well as it's possible to change only the case of file- and directory names.<br />
<br />
The same applies to equally named files and directories on the same level in the folder hierarchy, i.e. it's not possible to create a new file in a directory where an equally (ignoring case) named subdirectory already exists and vice versa.<br />
<br />
There is a similar restriction regarding file and directory names in the same directory having different unicode normalization forms, yet the same textual representation. OX Drive requires uniqueness regarding this textual representaion of potentially different encoded unicode strings. So, in case the client tries to synchronize two textually equal files or directories, he is instructed to put one of them into quarantine. Internally the server performs an equals-check of the "NFC" normalization forms of the strings, i.e. an unicode string is normalized using full canonical decomposition, followed by the replacement of sequences with their primary composites, if possible. Details regarding unicode normalization can be found at http://www.unicode.org/reports/tr15/tr15-23.html .<br />
<br />
== Invalid and ignored Filenames ==<br />
<br />
There are some filenames that are invalid or ignored and therefore not synchronized. This means that files with these names should not be taken into account when sending the directory contents to the server, or when calculating the directory checksum (see below). The following list describes when a filename is considered invalid:<br />
* If it contains one or of the following reserved characters: <br />
** <code><</code> (less than), <br />
** <code>></code> (greater than)<br />
** <code>:</code> (colon)<br />
** <code>"</code> (double quote)<br />
** <code>/</code> (forward slash)<br />
** <code>\</code> (backslash)<br />
** <code>|</code> (vertical bar or pipe)<br />
** <code>?</code> (question mark)<br />
** <code>*</code> (asterisk)<br />
** Characters whose integer representations are in the range from 0 through 31<br />
* The last character is a <code>.</code> (dot) or <code>' '</code> (space)<br />
* It's case-invariant name without an optional extension matches one of the reserved names <code>CON</code>, <code>PRN</code>, <code>AUX</code>, <code>NUL</code>, <code>COM1</code>, <code>COM2</code>, <code>COM3</code>, <code>COM4</code>, <code>COM5</code>, <code>COM6</code>, <code>COM7</code>, <code>COM8</code>, <code>COM9</code>, <code>LPT1</code>, <code>LPT2</code>, <code>LPT3</code>, <code>LPT4</code>, <code>LPT5</code>, <code>LPT6</code>, <code>LPT7</code>, <code>LPT8</code>, or <code>LPT9</code><br />
* It consists solely of whitespace characters<br />
<br />
The following list gives an overview about the ignored filenames:<br />
* <code>desktop.ini</code><br />
* <code>Thumbs.db</code><br />
* <code>.DS_Store</code><br />
* <code>icon\r</code><br />
* Any filename ending with <code>.drivepart</code><br />
* Any filename starting with <code>.msngr_hstr_data_</code> and ending with <code>.log</code><br />
<br />
Nevertheless, if the client still insists to send a file version with an invalid or ignored filename, the file creation on the server is refused with a corresponding <code>error</code> action (see below). <br />
<br />
== Invalid and ignored Directory Names ==<br />
<br />
There are also similar restrictions regarding invalid directory names. Any try to include them in the list of directory versions will be responded with a corresponding error action for the directory version. The following list describes when a path is considered invalid:<br />
* If it contains one or of the following reserved characters: <br />
** <code><</code> (less than), <br />
** <code>></code> (greater than)<br />
** <code>:</code> (colon)<br />
** <code>"</code> (double quote)<br />
** <code>\</code> (backslash)<br />
** <code>|</code> (vertical bar or pipe)<br />
** <code>?</code> (question mark)<br />
** <code>*</code> (asterisk)<br />
** Characters whose integer representations are in the range from 0 through 31<br />
* The last character of any subpath (i.e. the last part of the whole path or the part preceding the spearator character <code>/</code>) is a <code>.</code> (dot) or <code>' '</code> (space)<br />
* It consists solely of whitespace characters<br />
* It not equals the root path <code>/</code>, but ends with a <code>/</code> (forward slash) character<br />
* It contains two or more consecutive <code>/</code> (forward slash) characters<br />
<br />
The following list gives an overview about the ignored directory names:<br />
* <code>/.drive</code><br />
* Any directory whose path ends with <code>/.msngr_hstr_data</code><br />
<br />
== Length Restrictions ==<br />
<br />
The maximum allowed length for path segments, i.e. the parts between forawrd slashes (</code>/</code>) in directory and filenames, is restricted to 255 characters. Synchronizing a file or directory version that contains path segments longer than this limit leads to those versions being put into quarantine.<br />
<br />
= Client side filtering =<br />
<br />
Client-side filtering is available since API version 2. <br /> <br />
<br />
OX Drive clients may define a user- and/or application-defined list of file- and directory name exclusions. Those exclusion filters are then taken into account during synchronization, i.e. files and directories matching a defined exclusion pattern are ignored when comparing the list of server-, client- and original versions. Also, the file exclusion lists are considered for the calculation of aggergated directory checksums.<br />
<br />
The exclusion filters may be set, changed or unset at any time during synchronization, there are no additional requests needed to set them up. Instead, the list of excluded files and directories is simply sent along with each <code>syncFolders</code>, <code>syncFiles</code> and <code>download</code> request. The following tables show the JSON representation of file- and directory patterns that are used to build up the exlcusion lists:<br />
<br />
== Directory pattern ==<br />
<br />
A directory pattern is defined by a pattern string and further attributes.<br />
<br />
{| id="DirectoryPattern" cellspacing="0" border="1"<br />
|+ align="bottom" | Directory Pattern<br />
! Name !! Type !! Value<br />
|-<br />
| type || String || The pattern type, currently one of <code>exact</code> or <code>glob</code>. <br />
|-<br />
| path || String || The path pattern, in a format depending on the pattern type. <br />
|-<br />
| caseSensitive || Boolean | Optional flag to enable case-sensitive matching, defaults to <code>false</code> <br />
|}<br />
<br />
== File pattern ==<br />
<br />
A file pattern is defined by pattern strings for the filename and path, as well as further attributes.<br />
<br />
{| id="FilePattern" cellspacing="0" border="1"<br />
|+ align="bottom" | File Pattern<br />
! Name !! Type !! Value<br />
|-<br />
| type || String || The pattern type, currently one of <code>exact</code> or <code>glob</code>. <br />
|-<br />
| path || String || The path pattern, in a format depending on the pattern type. <br />
|-<br />
| name || String || The filename pattern, in a format depending on the pattern type.<br />
|-<br />
| caseSensitive || Boolean | Optional flag to enable case-sensitive matching, defaults to <code>false</code> <br />
|}<br />
<br />
== Pattern types ==<br />
<br />
A pattern currently may be defined in two formats: <code>exact</code> or <code>glob</code>.<br />
<br />
* <code>exact</code> <br /> An exact pattern, matching the file- or directory version literally. For example, to exclude the file <code>Backup.pst</code> in the subfolder <code>Mail</code> below the root synchronization folder, an <code>exact</code> file pattern would look like: <code>{"path":"/Mail","name":"Backup.pst","type":"exact"}</code>, or, an <code>exact</code> directory pattern for the directory <code>/Archive</code> would be represented as <code>{"path":"/Archive","type":"exact"}</code>.<br />
* <code>glob</code> <br /> A simple pattern allowing to use the common wildcards <code>*</code> and <code>?</code> to match file- and directory versions. For example, to exclude all files ending with <code>.tmp</code> across all directories, the <code>glob</code> file pattern could be defined as <code>{"path":"*","name":"*.tmp","type":"glob"}</code>, or, to exclude the directory <code>/Project/.git</code> and all its subdirectories recursively, this would be expressed using a combination of the following two directory patterns: <code>[{"path":"/Project/.git","type":"exact"},{"path":"/Project/.git*","type":"glob"}]</code>.<br />
<br />
== Further considerations ==<br />
<br />
* It's possible to exclude a (parent) directory with an appropriate pattern, while still subfolders below that directory being synchronized. This usually results in the excluded directory being created ob both client- and server side, but no file contents within the excluded directory being exchanged. If subfolders should be excluded, too, a wildcard should be used in the pattern to match any subdirectories.<br />
* If the client tries to synchronize a file- or directory version that is ignored, i.e. a version that would match any of the provided exclusion filters, the server behaves similarly to the handling of invalid and ignored file- and directory names (see above), i.e. the client would be instructed to put those versions into quarantine.<br />
* For the calculation of directory checksums, it's important that the server and client perform exactly the same matching for ignored filenames: A <code>*</code> character matches zero or more characters, a <code>?</code> character matches exactly one character. All other characters are matched literally. Advanced glob flavors like braces to define subpattern alternatives or square brackets for character sets are not used. <br />
* Client-side filtering is available with API version 2. The API version that is supported by the server is included in the response of the [[#Get Settings | Settings]] request.<br />
* Whenever there are active exclusion filters, the <code>syncFolders</code> request should contain all of both directory and file exclusion filter lists. For the <code>syncFiles</code> request, it's sufficient to include the list of file exclusions.<br />
<br />
<br />
= Metadata Synchronization =<br />
<br />
The synchronization of metadata is available since API version 3. <br /> <br />
<br />
== Introduction ==<br />
<br />
Previously, only the "raw" folders and files were synchronized between server and clients. While this is sufficient for basic synchronization, there are cases where the clients could benefit from additional data - "metadata" - that is already available on the server. For example, clients could display directories that have been shared or published to other people in a different way. Or, clients could consider folder permissions directly in case the user is performing a local change that would be rejected by the server in the next synchronization cycle anyway.<br />
<br />
To supply the clients with those additional information without any influence on the existing synchronization protocol (!), <code>.drive-meta</code> files are introduced for each synchronized directory. Regarding synchronization, such files are treated like any other ordinary file. Especially, those files are taken into account when it comes to directory checksum calculation. Doing so, metadata updates result in a changed <code>.drive-meta</code> file, which in turn causes the parent directory checksum to change, hence synchronization is triggered. <br />
<br />
However, some special handling applies for those files:<br />
<br />
* Clients are not allowed to change metadata, so modifications of metadata files or the deletion of them is rejected. Recovery is done via the protocol here, i.e. the client is instructed to re-download the file.<br />
* <code>.drive-meta</code> files are actually not stored physically on the file storage backend, but created on the fly based on the actual metadata of the directory.<br />
* Client applications may either store such files on the client file system, or evaluate and store the contained metadata information in a local database for later retrieval. If the file is not saved physically on the client (which is actually recommended), the client is responsible to consider the metadata file in a virtual way and include it's checksum for the directory checksum calculation - similar to the server's internal handling.<br />
<br />
Note: Embedded metadata synchronization is enabled by default, but can be forcibly disabled by setting the <code>driveMeta</code> parameter to <code>false</code> in each request.<br />
<br />
== Metadata format ==<br />
<br />
The metadata in <code>.drive-meta</code> files is serialized in JSON format to allow easy processing at the clients. The following shows an example of the contents:<br />
{<br />
"path": "/",<br />
"localized_name": "Meine Dateien",<br />
"own_rights": 403710016,<br />
"permissions": [{<br />
"bits": 403710016,<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
}],<br />
"shareable": true,<br />
"jump": ["permissions"],<br />
"files": [{<br />
"name": "Koala.jpg",<br />
"created": 1418024190565,<br />
"modified": 1418026995663,<br />
"created_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"modified_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"preview": "http://192.168.32.191/ajax/files?action=document&folder=268931&id=268931/297620&version=1&delivery=download&scaleType=contain&width=800&height=800&rotate=true",<br />
"thumbnail": "http://192.168.32.191/ajax/files?action=document&folder=268931&id=268931/297620&version=1&delivery=download&scaleType=contain&width=100&height=100&rotate=true",<br />
"object_permissions": [{<br />
"bits": 1,<br />
"group": false,<br />
"entity": 10,<br />
"display_name": "Klaus Mander",<br />
"email_address": "klaus.mander@example.com",<br />
"guest": false<br />
},<br />
{<br />
"bits": 1,<br />
"group": false,<br />
"entity": 8338,<br />
"email_address": "horst@example.com",<br />
"guest": true<br />
}],<br />
"shareable": true,<br />
"shared": true,<br />
"number_of_versions": 1,<br />
"version": "1",<br />
"jump": ["preview",<br />
"permissions",<br />
"version_history"]<br />
},<br />
{<br />
"name": "test.txt",<br />
"created": 1418024198520,<br />
"modified": 1418027394897,<br />
"created_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"modified_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"preview": "http://192.168.32.191/ajax/files?action=document&format=preview_image&folder=268931&id=268931/297621&version=6&delivery=download&scaleType=contain&width=800&height=800",<br />
"thumbnail": "http://192.168.32.191/ajax/files?action=document&format=preview_image&folder=268931&id=268931/297621&version=6&delivery=download&scaleType=contain&width=100&height=100",<br />
"locked": true,<br />
"shareable": true,<br />
"number_of_versions": 4,<br />
"version": "6",<br />
"version_comment": "Uploaded with OX Drive (TestDrive)",<br />
"versions": [{<br />
"name": "test.txt",<br />
"file_size": 23,<br />
"created": 1418024198520,<br />
"modified": 1418024202878,<br />
"created_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"modified_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"version": "1",<br />
"version_comment": "Uploaded with OX Drive (TestDrive)"<br />
},<br />
{<br />
"name": "test.txt",<br />
"file_size": 54,<br />
"created": 1418024234782,<br />
"modified": 1418024231522,<br />
"created_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"modified_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"version": "2",<br />
"version_comment": "Uploaded with OX Drive (TestDrive)"<br />
},<br />
{<br />
"name": "test.txt",<br />
"file_size": 120,<br />
"created": 1418027349026,<br />
"modified": 1418027355957,<br />
"created_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"modified_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"version": "5"<br />
},<br />
{<br />
"name": "test.txt",<br />
"file_size": 127,<br />
"created": 1418027370051,<br />
"modified": 1418027366945,<br />
"created_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"modified_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"version": "6",<br />
"version_comment": "Uploaded with OX Drive (TestDrive)"<br />
}],<br />
"jump": ["preview",<br />
"edit",<br />
"permissions",<br />
"version_history"]<br />
},<br />
{<br />
"name": "Kalimba.mp3",<br />
"created": 1418026529047,<br />
"modified": 1247549551659,<br />
"created_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"modified_by": {<br />
"group": false,<br />
"entity": 182,<br />
"display_name": "Mander, Jens",<br />
"email_address": "jens.mander@example.com",<br />
"guest": false<br />
},<br />
"preview": "http://192.168.32.191/ajax/image/file/mp3Cover?folder=268931&id=268931/297623&version=1&delivery=download&scaleType=contain&width=800&height=800",<br />
"thumbnail": "http://192.168.32.191/ajax/image/file/mp3Cover?folder=268931&id=268931/297623&version=1&delivery=download&scaleType=contain&width=100&height=100",<br />
"shareable": true,<br />
"number_of_versions": 1,<br />
"version": "1",<br />
"version_comment": "Uploaded with OX Drive (TestDrive)",<br />
"jump": ["preview",<br />
"permissions",<br />
"version_history"]<br />
}]<br />
}<br />
<br />
The following objects describe the JSON structure of the metadata for a directory:<br />
<br />
{| id="DirectoryMetadata" cellspacing="0" border="1"<br />
|+ align="bottom" | Directory Metadata<br />
! Name !! Type !! Value<br />
|-<br />
| id || String || The server-side unique identifier of the directory. <br />
|-<br />
| localized_name || String || The localized display name of the directory, if different from the physical name.<br />
|-<br />
| checksum || String || The directory's checksum. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].<br />
|-<br />
| own_rights || Number|| Folder permissions which apply to the current user, as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Permission Flags)]. <br />
|-<br />
| permissions || Array || All folder permissions, each element is an object as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Permission Object)]. <br />
|-<br />
| extended_permissions || Array || All folder permissions including some additional information, each element is an object as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Extended Permission Object)].<br />
|-<br />
| default_folder || Boolean || <code>true</code> if the folder is a default folder, <code>false</code> or not set, otherwise. <br />
|-<br />
| has_subfolders || Boolean || <code>true</code> if the folder (potentially) has subfolders, <code>false</code> or not set, otherwise. <br />
|-<br />
| shared || Boolean || <code>true</code> if the folder is shared, <code>false</code> or not set, otherwise. <br />
|-<br />
| shareable || Boolean || <code>true</code> if the folder can be shared to others by the user, <code>false</code> or not set, otherwise. <br />
|-<br />
| not_synchronizable || Boolean || <code>true</code> if the folder is exluded from synchronization, <code>false</code> or not set, otherwise. <br />
|-<br />
| type || Number || The special folder type, or not set, if not available. <br />
|-<br />
| jump || Array || An array containing the names of possible <code>jump</code> methods to use for the folder. <br />
|-<br />
| files || Array || Metadata for the contained files, each element is an object as described in [[#FileMetadata | File Metadata]]. Only set if metadata is retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].<br />
|}<br />
<br />
<br />
{| id="FileMetadata" cellspacing="0" border="1"<br />
|+ align="bottom" | File Metadata<br />
! Name !! Type !! Value<br />
|-<br />
| name || String || The name of the file the metadata belongs to. <br />
|-<br />
| checksum || String || The file's checksum. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].<br />
|-<br />
| path || String || The path of the parent directory. Only set if metadata is not retrieved through [[#Metadata_Synchronization|Metadata Synchronization]].<br />
|-<br />
| created || Timestamp || The file's last modification time (always UTC, not translated into user time). <br />
|-<br />
| modified || Timestamp || The file's last modification time (always UTC, not translated into user time). <br />
|-<br />
| created_by || Number || User ID of the user who created this object.<br />
|-<br />
| modified_by || Number || User ID of the user who last modified this object.<br />
|-<br />
| content_type || String || The content type of the file.<br />
|-<br />
| preview || String || A URL to a preview image for the file. <br />
|-<br />
| thumbnail || String || A URL to a thumbnail image for the file. <br />
|-<br />
| object_permissions || Array || All file permissions, each element is an object as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Object Permission Object)]. <br />
|-<br />
| extended_object_permissions || Array || All file permissions including some additional information, each element is an object as described in [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Extended Object Permission Object)]. <br />
|-<br />
| shared || Boolean || <code>true</code> if the file is shared, <code>false</code> or not set, otherwise. <br />
|-<br />
| shareable || Boolean || <code>true</code> if the file can be shared to others by the user, <code>false</code> or not set, otherwise. <br />
|-<br />
| locked || Boolean || <code>true</code> if the file is locked, <code>false</code> or not set, otherwise. <br />
|-<br />
| jump || Array || An array containing the names of possible <code>jump</code> methods to use for the file. <br />
|-<br />
| number_of_versions || Number | The number of all versions of the file. <br />
|-<br />
| version || String || The current version identifier (usually, but not necessarily a numerical value) of the file. <br />
|-<br />
| version_comment || String | An additional comment for the file version. <br />
|-<br />
| versions || Array || Metadata for all versions of the file, each element is an object as described in [[#File_Version | File Version]]. <br />
|}<br />
<br />
{| id="FileVersion" cellspacing="0" border="1"<br />
|+ align="bottom" | File Version<br />
! Name !! Type !! Value<br />
|-<br />
| name || String || The name of the file version. <br />
|-<br />
| file_size || Number || The file size of the version in bytes. <br />
|-<br />
| created || Timestamp || The file version's last modification time (always UTC, not translated into user time). <br />
|-<br />
| modified || Timestamp || The file version's last modification time (always UTC, not translated into user time). <br />
|-<br />
| created_by || Number || User ID of the user who created this object.<br />
|-<br />
| modified_by || Number || User ID of the user who last modified this object.<br />
|-<br />
| version || String || The version identifier (usually, but not necessarily a numerical value) of the file version. <br />
|-<br />
| version_comment || String || An additional comment for the file version. <br />
|}<br />
<br />
== Client-side implementation ==<br />
<br />
In order to make use of the metadata, clients should roughly implement the following:<br />
* Include the <code>apiVersion</code> parameter in each request, and set it to at least <code>3</code> in order to include <code>.drive-meta</code> during synchronization<br />
* Evaluate <code>.drive-meta</code> files and store the information, as well as the file's checksums in a local database<br />
* Include this file in the calculation of the parent directory checksum, just like an ordinary file in that directory<br />
* Do something useful with the metadata information.<br />
<br />
== Additional notes ==<br />
<br />
* The metadata synchronization via <code>.drive-meta</code> files embedded into the synchronization protocol obsoletes the previously used methods to receive metadata information ([[#Get_file_metadata]] and <code>columns</code> parameter in [[#Synchronize_files_in_a_folder]].<br />
* Depending on the underlying file storage backend, the included metadata may vary, so each information should be treatened as optional.<br />
* Embedded metadata synchronization is enabled by default, but can be forcibly disabled by setting the <code>driveMeta</code> parameter to <code>false</code> in each request.<br />
<br />
== Possible use cases ==<br />
* For files where the <code>locked</code> property is <code>true</code>, display some kind of "lock" icon (-overlay) in the file list / explorer view<br />
* For files or folders where the <code>shared</code> property is <code>true</code>, display some kind of "cloud" icon (-overlay) in the file list / explorer view<br />
* For files or folders where the user is not allowed to perform an action with, don't offer such actions (e.g. if a file cannot be deleted or renamed by the user due to insufficient permissions, disable the corresponding options)<br />
* Use the URLs in <code>preview</code> and <code>thumbnail</code> to get a preview image for the files<br />
* Display the server creation / last modification timestamps of files and folders<br />
* Embed a version history for files with multiple versions<br />
* Show to which users a file or folder is currently shared<br />
* Offer appropriate "jump" actions to the groupware web interface for more advanced options (e.g. to directly edit an .xlsx file in the spreadsheet application of the web interface, or to manage a folder's permission</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:ExternalLoginPage&diff=22105AppSuite:ExternalLoginPage2016-06-30T07:52:47Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>= How to set up an external login page for App Suite =<br />
<br />
== Who should read this document ==<br />
<br />
This document is written for web developers who would like to create a custom login mask for the OX App Suite. The login mask can reside on an external server i. e., not directly located in the domain of the Open-Xchange machines. It is also intended for administrators who install and maintain Open-Xchange services.<br />
<br />
<br />
== HTML ==<br />
<br />
The Open-Xchange [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Form login)] has a function to<br />
create a session from external.<br />
<br />
The full detailed explanation how the HTML form is used and errors can be handled can be found here:<br />
<br />
[[OXSessionFormLogin|OX Session Formlogin]]<br />
<br />
== Redirect to custom login ==<br />
<br />
Users can still access the original product login site. If this is not wanted the following Apache <br />
configuration for your VirtualHost can be used to redirect all requests to your custom login page:<br />
<br />
RewriteEngine On<br />
RewriteRule ^/appsuite/signin /custom-login.html [R]<br />
<br />
Since 7.8.0 it can be configured directly in <code>/opt/open-xchange/etc/as-config.yml</code><br />
<pre><br />
# Override certain settings<br />
default:<br />
host: all<br />
loginLocation: 'http://example.com/appsuite/mycustomlogin.html'<br />
</pre><br />
Note: you need to have the right syntax (like leading spaces) in the .yml file.<br />
<br />
== Setting custom login as logout location ==<br />
<br />
If users should be directed to the custom login form after logout from App Suite the following property can be set globally somewhere in /opt/open-xchange/etc/settings/. Either create a new properties file or add the option in any existing one. For more complex setups e.g. with different brands please check out how to set this property in context or user scope which is explained [[ConfigCascade|here]].<br />
<br />
io.ox/core//customLocations/logout=https://login.example.com<br />
<br />
For cases where only one custom login page exists for all users it's also recommended to set<br />
<br />
logoutLocation: 'https://login.example.com/'<br />
<br />
in '''/opt/open-xchange/etc/as-config.yml'''. This setting takes effect for example if an autologin session is expired. as-config.yml itself defines settings in dependence of the hostname configured for the Open-Xchange access.</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:MSISDN&diff=22104AppSuite:MSISDN2016-06-30T07:52:01Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div><div class="title">MSISDN Support</div><br />
<br />
'''Abstract.''' In this article, the support for MSISDN is described in detail. It allows sending emails to and receiving email from phone numbers.<br />
__TOC__<br />
== Enabling MSISDN Support ==<br />
MSISDN support is disabled by default. In order to enable this feature, you must define the capability '''msisdn'''. This is done by simply adding the word "msisdn" to the property "permissions" in '''/opt/openexchange/etc/permission.properties''':<br />
<br />
<pre><br />
permissions=...,msisdn<br />
</pre><br />
<br />
== Server Settings ==<br />
<br />
=== Default configuration ===<br />
By default, cellular_telephone1 (551) and cellular_telephone2 (552) are used for the phone number lookup. This setting applies for both the sender and the recipient dialogs. It can by configured as follows:<br />
<br />
<pre class="language-javascript"><br />
io.ox/contacts/msisdn/columns=['551', '552']<br />
</pre><br />
<br />
This hidden value is appened to sender and recipient telephone numbers (example: '+491615840292/TYPE=PLMN'). It's used internally as distinguishing mark and is not shown to the user.<br />
<br />
<pre class="language-javascript"><br />
io.ox/contacts/msisdn/suffix='/TYPE=PLMN'<br />
</pre><br />
<br />
=== Exemplary custom configuration ===<br />
Adding another phone number is straight-forward. Just add it as follows, for example, telephone_other (553):<br />
<br />
<pre class="language-javascript"><br />
io.ox/contacts/msisdn/columns=['551', '552', '553']<br />
</pre><br />
<br />
See [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (detailed contact data)] for all relevant columns.<br />
<br />
=== Setting default sender address ===<br />
A phone number can also be configured as default sender address. This can be customized via the [[AppSuite:User_management#changeuser|changeuser]] interface. Relevant setting is ''defaultsenderaddress'':<br />
<br />
<pre class="language-javascript"> <br />
./changeuser ... --defaultsenderaddress <stringvalue><br />
</pre></div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:HTTP_API&diff=22103AppSuite:HTTP API2016-06-30T07:49:40Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>#REDIRECT [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API]<br />
<!-- it's still the same, don't fork it, it will diverge way too fast with fixes still done for OX6 --></div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Architecture_Overview&diff=22102AppSuite:Architecture Overview2016-06-30T07:49:06Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>__NOTOC__<br />
This page gives an overview of the most important internal components, plugin capabilities, public interfaces (APIs) and data communication streams of the Open-Xchange server. <br />
<br />
[[File:appsuite_architecture_diagram_3.png|1200px]]<br />
<br />
<br />
=<span style="background:#dcdcdc">Frontend and client based communication flow </span>=<br />
*'''1''' All communication from and to the users client is purely based on HTTP. It is strongly recommended to use only encrypted HTTPS. For security reasons, some modules require HTTPS connections in the default configuration. The HTTP(S) communication is terminated at Apache.<br />
<br />
*'''2''' Within Apache, the mod_proxy_http module is used to forward the request to the OX server. Apache can also be used to configure session stickiness and load balancing in clustered environments.<br />
<br />
*'''3''' OX Web UI<br />
** The [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API] is the core API for all user functionality. Every function of the Web UI is using this API. In addition to that, all possible user functionality is available via this API and can be used from external applications as well. It is based on JSON via HTTP(S).<br />
** [http://oxpedia.org/wiki/index.php?title=Portal:AppSuite_UI Web UI Documentation]<br />
** [[HTTP_API_Examples|Programming Example]], how to use this API to build an Email widget, accessing the HTTP API<br />
<br />
*'''4''' The OXtender for Business Mobility is a server based Active Sync Implementation. The "Microsoft Exchange Active Sync" protocol supports Push via HTTPS, therefore the email backend needs to send push events to the OX server. Details, see: [[OXtender for Business Mobility Installation Guide]] and [[OX_EMail_Push_Introduction|Email Push Introduction]]. Serverside, the synchronization makes use of the "Universal Sync Module (USM)", which is a server bundle containing the synchronization logic for several clients. It also communicates via HTTP(S) transporting JSON objects.<br />
<br />
*'''5''' The [[OXtender 2 for Microsoft Outlook]] is a MAPI plugin, installed in the Outlook client to synchronize data between Outlook and the OX server. It makes use of the same HTTP(S) and JSON based communication to the Universal Sync Module (USM), like Active Sync.<br />
<br />
*'''6''' [[Caldav carddav Bundles|CalDAV and CardDAV]] interfaces are available to synchronize calendars and address books with Apple OS X and iOS applications as well as Thunderbird: [[CalDAVClients|CalDAV Clients]] and [[CardDAVClients|CardDAV Clients]].<br />
<br />
*'''7''' A WebDAV implementation provides the possibility to access the documents in the Files-module directly via any WebDAV client, like the Windows Explorer.<br />
<br />
=<span style="background:#dcdcdc">Administration, provisioning and operations related components and communication flow</span>=<br />
*'''11''' Data Migration and Im-/Export of user data can be done via automated tools, using these interfaces: <br />
** [[Using the import servlet]], [[Building an importer]]<br />
** [[Using the export servlet]], [[Building an exporter]], [[Export_ical/vcard| iCal/vCard]]<br />
** A tool is available to upload data from Outlook profiles or PST files to OX: [http://oxpedia.org/wiki/index.php?title=OX_Outlook_Uploader Outlook Uploader]<br />
<br />
*'''12''' All provisioning tasks, like creating and editing users can be done with [http://software.open-xchange.com/OX6/doc/OX6-Provisioning/ Commandline tools]. The command line tools make use of the Java RMI API internally.<br />
<br />
*'''13''' The native, central provisioning API is available via Java RMI and split into the [http://software.open-xchange.com/OX6/doc/RMI/admin-core/ Core API] and the [http://software.open-xchange.com/OX6/doc/RMI/admin-hosting/ HostingAPI].<br />
<br />
*'''14''' Central control panels and billing systems, which are not implemented in Java, can use the RMI API via the [http://software.open-xchange.com/products/appsuite/doc/SOAP/admin/OX-Admin-SOAP.html SOAP API], examples of its usage can be found [[Open-Xchange-SOAP | here]].<br />
** Standard integration via SOAP is available for OPWV Directory<br />
** for Parallels Operations Automation see [[PAIntegrationGuide| PA integration guide]]<br />
** for Parallels Plesk Panel see [[Plesk_Integration|Plesk integration guide]]<br />
** for cPanel see [[Open-Xchange_cPanel_Installation| cPanel installation]]<br />
<br />
*'''15''' Authentication is implementable via highly customizable plugins, different standard and custom implementations are available<br />
**[[Authentication IMAP Plugin description| IMAP]]<br />
** LDAP<br />
** Database<br />
** custom<br />
<br />
*'''16''' Monitoring the OX application is done via JMX, for a description see [[OX monitoring interface]], or a commandline tool<br />
** An example how to use the monitoring interface is available as pre-built Scripts for the monitoring tool Munin: [[OX munin scripts]]<br />
<br />
=<span style="background:#E5E5E5">Backend related components and communication flow</span>=<br />
*'''21''' All OX-internal data - users, contacts, calendars, tasks and document metadata is stored in a MySQL Database, accessed via JDBC<br />
**'''22''' Native MySQL contacts storage<br />
<br />
*'''23''' Other sources for contacts than the MySQL storage can also be used. For this an OSGi bundle needs to be implemented, overriding the standard contact storage.<br />
** An implementation using LDAP is publicly available<br />
** Several custom implementations are available on request or can be implemented by partners<br />
<br />
*'''24''' Email storage is accessed through the pluggable [http://software.open-xchange.com/OX6/doc/mal/ Mail Abstraction Layer API] <br />
** The default implementation uses IMAP<br />
** Sending Emails is done via SMTP<br />
** For Openwave Email MX, Stateless Edition see [http://owmessaging.com/ OPWV MX]<br />
** For Active Sync or Outlook the email backend needs to send push requests to the OX server, for details see [[OX_EMail_Push_Introduction|Email Push Introduction]]<br />
** Several custom implementations are available on request or can be implemented by partners<br />
<br />
*'''25''' Documents in the Files module are accessed via an API, which allows customized implementations.<br />
** The default in large environments is to use NFS<br />
** In small environments the local filesystem is used<br />
** [http://www.scality.com/ Scality] is also available<br />
** Several custom implementations are available on request or can be implemented by partners<br />
<br />
=<span style="background:#E5E5E5">Social/Public Data related components, plugins and communication flow</span>=<br />
<br />
A <em>subscription based plugin system</em> allows to access data from external systems like webmail systems or social networks. The underlying concept is called [[SocialOX]] and a list of some plugins can be found here: [[SupportedCrawler]]. The integrations of messaging, contacts and calendars are done via the official API of the respective 3rd-party-service if there is one. For authentication, OAuth is used for security and privacy control if available. All plugins use HTTP(S) connections to the external services only. Access to the external email systems is done via IMAP(S) or POP3(S), depending on the service.<br />
<br />
*'''31''' For subscription to an external calendar a plugin to subscribe to Google Calendar is available.<br />
<br />
*'''32''' Supported external messaging services are Twitter and SMS/MMS.<br />
<br />
*'''33''' Contacts can be imported from Xing, LinkedIn, MSN/Windows Live/Outlook.com, Yahoo and Google.<br />
<br />
*'''34''' External email accounts can be integrated via POP3(S) or IMAP(S)<br />
** There are pre-configured settings for many popular services so that users only need to enter their e-mail address and password.<br />
** Look here how to [[install and configure the mail-account plugin]].<br />
<br />
* '''35''' RSS feeds are loaded remotely, filtered for exploits and can be read in the UI<br />
<br />
* '''36''' Image services like Flickr and Tumblr are integrated directly into the UI, bypassing the backend completely. Authentication is handled via OAuth.<br />
<br />
=<span style="background:#dcdcdc">Publicly Available Plugins</span>=<br />
* An overview of the existing public plugins can be found here: [[Open-Xchange Plugin Overview]]. Many others are available on request or through partners.<br />
<br />
<br />
<br />
<br />
This page was last updated on 2015/01/20.<br />
Person responsible: [mailto:karsten.will@open-xchange.com?Subject=AppSuite%20Architecture%20Overview%20(oxpedia.org)&body=Hi%20Karsten%2C%0A%0AThere%20is%20something%20you%20should%20take%20care%20of%20at%20this%20wiki-page%3A%0Ahttp%3A%2F%2Foxpedia.org%2Fwiki%2Findex.php%3Ftitle%3DAppSuite%3AArchitecture_Overview%0A%0AIt%20is%3A Karsten Will] (creates new pre-filled email)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Introduction_to_the_HTTP_API&diff=22100AppSuite:Introduction to the HTTP API2016-06-30T07:46:48Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>== Introduction ==<br />
<br />
This document explains the basics of using the Open-Xchange HTTP API. This article describes general definitions and conventions which apply to all server modules. The (rather large) list of potential calls can be found at [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API].<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>/api</code>. Each server module has a unique name and its own sub-namespace with that name below <code>/api</code>, e. g. all access to the module "tasks" is via URIs starting with <code>/api/tasks</code>. This is different from the previous OX6, where it was /ajax (so you might keep that configuration, too, and run an OX6. Check the compatibility chart before doing so). <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 [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API (Updates)]).<br />
|-<br />
| error || String || English error message. Present in case of errors.<br />
|-<br />
| error_params || Array || Replacement parameters for the error message.<br />
|-<br />
| error_id || String || Unique error identifier to help finding this error instance in the server logs.<br />
|-<br />
| code || String || Error code consisting of a three-letter category and a four-digit message number, separated by a dash.<br />
|-<br />
| category || Number || Category to which the error message belongs:<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 />
| 7 || An internal java-related (runtime) exception.<br />
|-<br />
| 8 || A programming error which was caused by incorrect programm code.<br />
|-<br />
| 9 || A concurrent modification.<br />
|-<br />
| 10 || Error in system setup detected.<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 />
==== Detailed Exception Data (Preliminary) ====<br />
Starting with some upcoming version application errors will be returned in the field "exception" in a response. The exception field will contain a JSON array containing objects that have the format specified in the following table:<br />
<br />
{| id="ResponseBody" cellspacing="0" border="1"<br />
|+ align="bottom" | Exception Object<br />
! Name !! Type !! Value<br />
|-<br />
| code || String || Error code consisting of a three-letter category and a four-digit message number, separated by a dash.<br />
|-<br />
| category || Number || Category to which the error message belongs:<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 />
| 7 || An internal java-related (runtime) exception.<br />
|-<br />
| 8 || A programming error which was caused by incorrect programm code.<br />
|-<br />
| 9 || A concurrent modification.<br />
|-<br />
| 10 || Error in system setup detected.<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 />
| message || String || Localized error message. <br />
|-<br />
| parameters || Array || Replacement parameters for the message. ''What are they good for if the message is already localized? -- Viktor Pracht - 2009-04-24''<br />
|-<br />
| logMessage || String || Technical error message useful for debugging the problem. <br />
|-<br />
| exceptionId || String || Unique error identifier to help finding this error instance in the server logs. <br />
|-<br />
| help || String || Localized help text, telling the user how he may resolve the problem. <br />
|-<br />
| session || String || The session id of the session in which this exception was caused. ''When can this be '''not''' the current session? -- Viktor Pracht - 2009-04-24''<br />
|-<br />
| user || Number || The id of the user having caused the exception. ''When can this be '''not''' the current user? -- Viktor Pracht - 2009-04-24''<br />
|-<br />
| context || Number || The context id of the context in which the exception happened. ''When can this be '''not''' the current context? -- Viktor Pracht - 2009-04-24''<br />
|-<br />
| details || Object || A JSON Object containing extra information for debugging purposes. <br />
|-<br />
| application || String || Application ID of the subsystem having thrown this exception. <br />
|-<br />
| stacktrace || Array || An array of Strings containing the error trace. Note: This can be turned off in the backend, in which case an empty array will be returned. <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 />
<html><br />
<head><br />
<script type="text/javascript"><br />
(owner || parent).callback_<b>action</b>(<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.</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Template:OX7:Main_Page_Advanced&diff=22099Template:OX7:Main Page Advanced2016-06-30T07:43:46Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>'''Under Construction'''<br />
<br />
__NOTOC__<br />
= Overview =<br />
*[[AppSuite:Architecture_Overview|Architecture Overview]]<br />
<br />
= Branding =<br />
* [[Whitelabel|White-labeling the Open-Xchange GUI for big hosting/reseller environments]]<br />
* [[Gui_Theming_Description|GUI Theming Description]]<br />
* [[User_and_context_based_themes|User and context based themes]]<br />
* [[Gui_Plugin_Development|GUI Branding Plugins]]<br />
<br />
= UI Customization and Examples =<br />
* [[Gui_Plugin_Development|Embedding external web applications which require authentication]]<br />
* [[Gui_path|Setting User/GUI Preferences via RMI]]<br />
* [[Open-Xchange_UWA|Open-Xchange Netvibes UWA mashup]]<br />
* [[Gui_Plugin_Development|GUI Plugin Development]]<br />
* [[Plugin_API|GUI Plugin API Documentation]]<br />
* [[Enable_TinyMCE_spellcheck_module|Enable the TinyMCE spell-checker module]]<br />
* [[HTTP_API_Examples|HTTP API Examples]]<br />
* [[Install_and_configure_the_mail-account_plugin|Install and configure the mail-account plugin]]<br />
<br />
= Groupware Server customization =<br />
* [[Automatic_Delete_OXObjects_Per_User|Automatically delete users OX-Objects and OX-Folders]]<br />
* Auto login, session handling, single sign on<br />
** [http://www.open-xchange.com/fileadmin/user_upload/open-xchange/document/presentation/OX-HE-Authentication-Sessionhandling-en-6.18.pdf Authentication and Sessionhandling white paper (EasyLogin)]<br />
** Custom login masks<br />
*** [[Open-Xchange servlet for external login masks]]<br />
<br />
= Programming Interfaces =<br />
* The [https://documentation.open-xchange.com/latest/middleware/http_api.html HTTP API] is used by the Open-Xchange GUI and various 3rd party applications. It consists mainly of messages in JavaScript Object Notation ([http://json.org JSON]) sent over HTTP.<br />
* Provisioning API to access the Open-Xchange Admin Daemon<br />
** The [http://java.sun.com/javase/technologies/core/basic/rmi/index.jsp RMI] API is used for data provisioning of Contexts, Users, Groups and Resources as well as for configuring Databases, Filestores and OX Servers. It is currently split into two parts,<br />
*** a {{DocLink|docpath=RMI/admin-core/|name=core}} and<br />
*** a {{DocLink|docpath=RMI/admin-hosting/|name=hosting}} component.<br />
** The {{DocLink|docpath=OX6-Provisioning/|name=Open-Xchange CLT}} are shell scripts that simplify groupware and service administration<br />
** Create contexts/users with with [[Csv_import]]<br />
** [[Open-Xchange-SOAP|Provisioning using SOAP]]<br />
* The [[Oxmapi|Oxmapi]] is a windows library for programmers needed to communicate with the OX server<br />
* {{DocLink|docpath=mal/|name=Open-Xchange Mail Abstraction Layer}}<br />
* The Plugin API for extending the GUI is described in two documents: [[Plugin API|an overview]] and {{DocLink|docpath=gui-plugin-api|name=the reference}}<br />
* [[UDPPush]] Open-Xchange PUSH Interface for Groupware Objects<br />
<br />
{{=}} Importing and exporting data {{=}}<br />
* Migrate a batch of users and contexts at once. Check the CSV Batch Import documentation [[Csv_import|page]].<br />
* Documentation for the [[data import format|data import format]]<br />
* [[VCard and ICal support]]<br />
* [[Using the export servlet]]<br />
* [[Using the import servlet]]<br />
* [[export ical/vcard|Example in bash to extract private contacts,tasks,appointments in ical/vcard format]]<br />
* [[Import_holidays|Importing holidays into the OX Calendar]]<br />
* [[CrawlerArchitecture|Architecture of the crawler bundle]]<br />
<br />
{{=}} Configuration and Tweaks {{=}}<br />
* [[OX6_Troubleshooting|Basic troubleshooting]]<br />
* {{DocLink|docpath=Html-Whitelist|name=HTML Whitelist configuration}}<br />
* [[Open_Xchange_Configuration|Open-Xchange Configuration]]<br />
* [[Open-Xchange_RSS_Client|Open-Xchange as RSS client]]<br />
* [[On_The_Fly_Configuration_Update|On The Fly Configuration Update (experimental)]]<br />
* [[Session_Migration|Session migration]]<br />
* [[Syslog_Configuration|syslog Configuration]]<br />
* [[OXAE_MailingLists_with_contacts-ldap|Integrate OXAE Mailinglists into Open-Xchange]]<br />
* [[MailNotify_Bundle|Mail Notification (Push) with Open-Xchange]]<br />
* [[UCS_AD_Connector_en|Synchronize Active Directory with OX ASE/SE for UCS]]<br />
* [[Tune_apache2_for_more_concurrent_connections|Apache2 tuning]]<br />
<br />
= Testing and QA =<br />
* [[Automated GUI Tests]]<br />
* [[Jmeter profile for performance tests|JMeter profile for performance tests]]<br />
<br />
= Translations =<br />
* [[Available_Translation| Available Language Translations]]<br />
* [[GUI Translation|Translate Open-Xchange to your community language]]<br />
* [[Translate Open-Xchange to supported language]]<br />
<br />
= Installation based on source code =<br />
* [[SourceCodeAccess|Download the sourcecode]]<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Category:HTTP_API&diff=22098Category:HTTP API2016-06-29T13:59:11Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>Articles that describe the HTTP API of a bundle, which usually means the exchange of JSON messages over http or https. The bundles documented here are optional bundles. Core functionalities are described in [https://documentation.open-xchange.com/ HTTP API].</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Template:Main_Page_Advanced&diff=22096Template:Main Page Advanced2016-06-29T13:57:22Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>__NOTOC__<br />
= Overview =<br />
*[[AppSuite:Architecture_Overview|Architecture Overview]]<br />
<br />
= Branding =<br />
* [[Whitelabel|White-labeling the Open-Xchange GUI for big hosting/reseller environments]]<br />
* [[Gui_Theming_Description|GUI Theming Description]]<br />
* [[User_and_context_based_themes|User and context based themes]]<br />
* [[Gui_Plugin_Development|GUI Branding Plugins]]<br />
<br />
= UI Customization and Examples =<br />
* [[Gui_Plugin_Development|Embedding external web applications which require authentication]]<br />
* [[Gui_path|Setting User/GUI Preferences via RMI]]<br />
* [[Open-Xchange_UWA|Open-Xchange Netvibes UWA mashup]]<br />
* [[Gui_Plugin_Development|GUI Plugin Development]]<br />
* [[Plugin_API|GUI Plugin API Documentation]]<br />
* [[Enable_TinyMCE_spellcheck_module|Enable the TinyMCE spell-checker module]]<br />
* [https://documentation.open-xchange.com/ HTTP API Examples]<br />
* [[Install_and_configure_the_mail-account_plugin|Install and configure the mail-account plugin]]<br />
<br />
= Groupware Server customization =<br />
* [[Automatic_Delete_OXObjects_Per_User|Automatically delete users OX-Objects and OX-Folders]]<br />
* Auto login, session handling, single sign on<br />
** [http://www.open-xchange.com/fileadmin/user_upload/open-xchange/document/presentation/OX-HE-Authentication-Sessionhandling-en-6.18.pdf Authentication and Sessionhandling white paper (EasyLogin)]<br />
** Custom login masks<br />
*** [[Open-Xchange servlet for external login masks]]<br />
<br />
= Programming Interfaces =<br />
* The [https://documentation.open-xchange.com/ HTTP API] is used by the Open-Xchange GUI and various 3rd party applications. It consists mainly of messages in JavaScript Object Notation ([http://json.org JSON]) sent over HTTP.<br />
* Provisioning API to access the Open-Xchange Admin Daemon<br />
** The [http://java.sun.com/javase/technologies/core/basic/rmi/index.jsp RMI] API is used for data provisioning of Contexts, Users, Groups and Resources as well as for configuring Databases, Filestores and OX Servers. It is currently split into two parts,<br />
*** a {{DocLink|docpath=RMI/admin-core/|name=core}} and<br />
*** a {{DocLink|docpath=RMI/admin-hosting/|name=hosting}} component.<br />
** The {{DocLink|docpath=OX6-Provisioning/|name=Open-Xchange CLT}} are shell scripts that simplify groupware and service administration<br />
** Create contexts/users with with [[Csv_import]]<br />
** [[Open-Xchange-SOAP|Provisioning using SOAP]]<br />
* The [[Oxmapi|Oxmapi]] is a windows library for programmers needed to communicate with the OX server<br />
* {{DocLink|docpath=mal/|name=Open-Xchange Mail Abstraction Layer}}<br />
* The Plugin API for extending the GUI is described in two documents: [[Plugin API|an overview]] and {{DocLink|docpath=gui-plugin-api|name=the reference}}<br />
* [[UDPPush]] Open-Xchange PUSH Interface for Groupware Objects<br />
<br />
{{=}} Importing and exporting data {{=}}<br />
* Migrate a batch of users and contexts at once. Check the CSV Batch Import documentation [[Csv_import|page]].<br />
* Documentation for the [[data import format|data import format]]<br />
* [[VCard and ICal support]]<br />
* [[Using the export servlet]]<br />
* [[Using the import servlet]]<br />
* [[export ical/vcard|Example in bash to extract private contacts,tasks,appointments in ical/vcard format]]<br />
* [[Import_holidays|Importing holidays into the OX Calendar]]<br />
* [[CrawlerArchitecture|Architecture of the crawler bundle]]<br />
<br />
{{=}} Configuration and Tweaks {{=}}<br />
* [[OX6_Troubleshooting|Basic troubleshooting]]<br />
* {{DocLink|docpath=Html-Whitelist|name=HTML Whitelist configuration}}<br />
* [[Open_Xchange_Configuration|Open-Xchange Configuration]]<br />
* [[Session_Migration|Session migration]]<br />
* [[Syslog_Configuration|syslog Configuration]]<br />
* [[OXAE_MailingLists_with_contacts-ldap|Integrate OXAE Mailinglists into Open-Xchange]]<br />
* [[MailNotify_Bundle|Mail Notification (Push) with Open-Xchange]]<br />
* [[Tune_apache2_for_more_concurrent_connections|Apache2 tuning]]<br />
* [[Running a cluster]]<br />
* [[Java startup parameters]]<br />
* [[Handling spam]]<br />
<br />
= Testing and QA =<br />
* [[Automated GUI Tests]]<br />
* [[Jmeter profile for performance tests|JMeter profile for performance tests]]<br />
<br />
= Translations =<br />
* [[Available_Translation| Available Language Translations]]<br />
* [[GUI Translation|Translate Open-Xchange to your community language]]<br />
* [[Translate Open-Xchange to supported language]]<br />
<br />
= Installation based on source code =<br />
* [[SourceCodeAccess|Download the sourcecode]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Template:Main_Developer&diff=22095Template:Main Developer2016-06-29T13:53:50Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>=== Interfaces ===<br />
* The [https://documentation.open-xchange.com/ HTTP API] is used by the new AJAX GUI. It consists mainly of messages in JavaScript Object Notation ([http://json.org JSON]) sent over HTTP.<br />
* Provisioning API to access the Open-Xchange Admin Daemon<br />
** The [http://java.sun.com/javase/technologies/core/basic/rmi/index.jsp RMI] API is used for data provisioning of Contexts, Users, Groups and Resources as well as for configuring Databases, Filestores and OX Servers. It is currently split into two parts,<br />
*** a {{DocLink|docpath=RMI/admin-core/|name=core}} and<br />
*** a {{DocLink|docpath=RMI/admin-hosting/|name=hosting}} component.<br />
** The {{DocLink|docpath=OX6-Provisioning/|name=Open-Xchange Hyperion CLT}} are shell scripts that simplify groupware and service administration<br />
** {{DocLink|docpath=SOAP/admin/OX-Admin-SOAP.html|name=Provisioning using SOAP}}<br />
* The [[Oxmapi|Oxmapi]] is a windows library for programmers needed to communicate with the OX server<br />
* {{DocLink|docpath=mal/|name=Open-Xchange Mail Abstraction Layer}}<br />
* The Plugin API for extending the GUI is described in two documents: [[Plugin API|an overview]] and {{DocLink|docpath=gui-plugin-api|name=the reference}}<br />
* [[UDPPush]] Open-Xchange PUSH Interface for Groupware Objects</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Plugin_API&diff=22094Plugin API2016-06-29T13:52:42Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>The Open-Xchange plugin API is a set of JavaScript objects and classes which can be used to extend the Open-Xchange GUI. The API is very new and still growing. Suggestions about desired functionality are always welcome on the [[API Suggestions]] page. As the API evolves, certain interfaces may change or be replaced by newer ones. When this happens, the old interfaces will be marked as "deprecated", but will continue to work long enough to allow all affected code to be updated.<br />
<br />
A reference of all currently available classes and functions of the plugin API is available at [[Main_Page_HESE#Programming_Interfaces|Programming interfaces (OX6)]] and [[AppSuite:Main_Page_AppSuite#Programming_Interfaces|Programming Interfaces (AppSuite)]]. The reference for any other version since Service Pack 5 can be created by checking out the corresponding GUI source code from CVS and executing the <code>jsdoc</code> Ant target in the top directory of the GUI source. The documentation is then placed in the directory <code>sdk/jsdoc</code> by default, but the location can be changed by defining the Ant property <code>jsdoc.dir</code> on the command line.<br />
<br />
This page complements the API reference as a guide to the creation of a GUI plugin. It starts with a description of a mininmal plugin, which is then expanded with examples of various API functionality.<br />
<br />
== Hello, World! ==<br />
<br />
First of all, every plugin needs a unique name. This name will be used in many places to avoid conflicts with other plugins which may be installed on the same server. The simplest way to come up with a unique name is to pick any name and prefix it with a domain name you control. The individual parts of the domain should be reversed like in Java (and other languages) package names. If we pick the canonical example domain <code>example.com</code> and name our plugin "test", then its unique name would be <code>com.example.test</code>.<br />
<br />
After choosing a name, we can start creating the actual plugin. The entire plugin must be contained in a single directory, which has the same name as the plugin. This directory will be installed on the server, and is the first example where the name must be unique to avoid overwriting other people's plugins.<br />
<br />
The entire JavaScript source code for the plugin must be put in a file called <code>register.js</code>. This file is loaded and executed when the GUI is initialized after the user logs in. The primary task of this file is to register the plugin and hook it up inside the GUI.<br />
<br />
For the first plugin, we only want to see when our code gets executed. For this, a simple alert will do:<br />
<br />
alert(<span style="color: #008">"Hello, World!"</span>);<br />
<br />
That's it! The absolutely minimal plugin is done and ready to be installed.<br />
<br />
== Installation ==<br />
<br />
To install the plugin, the directory which contains the <code>register.js</code> file is copied to the server into the <code>plugins</code> subdirectory of the GUI installation. For example, if the GUI is installed in <code>/var/www/</code>, then the plugin code will end up in <code>/var/www/plugins/com.example.test/register.js</code>.<br />
<br />
To enable the installed plugin, the GUI configuration [https://documentation.open-xchange.com/ HTTP API (Module "config")] provided by the server must contain an entry for the plugin. This can be accomplished either dynamically (e. g. per-user or per-context) by an OSGi bundle, or statically in a configuration file. We will use the latter method to enable the plugin for testing. The GUI configuration entry is added through a Java properties file in the <code>settings</code> subdirectory of the application server's configuration directory. Usually, this will be <code>/opt/openexchange/etc/groupware/settings/</code>. To avoid conflicts with configuration files for other plugins, again, the unique name of the plugin should be used together with the <code>.properties</code> file extension, e. g. <code>com.example.test.properties</code>. This file can now be used to add arbitrary entries to the GUI configuration by specifying the full path (separated by slashes) as the key and the value for each leaf configuration node as the value of a property. Inner nodes of the configuration tree don't need to be specified explicitly, they have no own values and are created automatically.<br />
<br />
The node required to enable the plugin must be a direct child of the node <code>modules</code> and have the same name as the plugin. The plugin is enabled if this node itself has children, or if its value is <code>true</code>. Since our plugin doesn't need any other settings yet, we use the latter variant:<br />
<br />
modules/com.example.test = true<br />
<br />
After (re)starting the server and logging in, the alert pop-up appears when the plugin is initialized. Since the initialization of all plugins happens immediately after logging in, plugins should perform only the minimum necessary initialization directly in <code>register.js</code>, and do the rest in some callback, e. g. when the user first interacts with the plugin.<br />
<br />
== Configuration tree ==<br />
<br />
After the plugin itself works, we can add some real functionality to it. Currently, the only place where plugins are supported is the configuration area. There one can add nodes to the configuration tree on the left, and add pages which are displayed when a node is clicked. Nodes can be added directly to the root node of the tree, or to other inner nodes, which look like folders. New inner nodes can also be added. While multiple levels of inner nodes would work, is it discouraged because of too many clicks a user would have to perform to get to the actual configuration pages.<br />
<br />
First, we add an inner node named "Example":<br />
<br />
'''new''' ox.Configuration.InnerNode(<span style="color: #008">"configuration/com.example.test"</span>, _(<span style="color: #008">"Example"</span>));<br />
<br />
The above line replaces the <code>alert</code> statement of the "Hello, World!" plugin. After reloading the GUI and clicking on the configuration module, there should be a new entry in the configuration tree. If the alert still appears, the browser cache must be cleared before reloading the GUI, or even better, the Apache module <code>mod_expires</code> should be disabled at least for the directory of the plugin.<br />
<br />
The constructor of the class <code>ox.Configuration.InnerNode</code> does all the work of creating the node object and adding it to the configuration tree. It accepts two parameters: the path and the name of the new node. The path of the node is similar to a file path in a directory tree. It specifies the location of the node as a list of path elements, separated by slashes. The root configuration node is called <code>configuration</code>. For the next level, plugins should use their unique name to avoid conflicts. If present, the last level can contain any strings, since it is usually defined by the plugin which created the second level.<br />
<br />
The second parameter, the name of the node, is a user-visible string which must be translated to the user's current language. The translation is performed by the function called <code>_</code> (that is, a single underscore). It is the same name as used by the [http://www.gnu.org/software/gettext/ GNU gettext] tools. Most other functions like <code>ngettext</code>, <code>pgettext</code> and <code>npgettext</code> are also available.<br />
<br />
Similar to inner nodes, leaf nodes are added by creating an object of the class <code>ox.Configuration.LeafNode</code>:<br />
<br />
'''var''' node = '''new''' ox.Configuration.LeafNode(<br />
<span style="color: #008">"configuration/com.example.test/account"</span>, _(<span style="color: #008">"Account"</span>));<br />
<br />
The <code>LeafNode</code> constructor takes the same parameters as the <code>InnerNode</code> constructor. This time, the created object is stored in the variable <code>node</code> because we still need it to add a page which is opened when the node is activated:<br />
<br />
'''var''' page = '''new''' ox.Configuration.Page(node, _(<span style="color: #008">"Account settings"</span>));<br />
<br />
The first parameter is the previously created inner node. The second parameter is the page title which is displayed at the top of the new page:<br />
<br />
[[Image:PluginAPIEmptyPage.png|center|Test page]]<br />
<br />
== Translation ==<br />
<br />
So far, all displayed text of the plugin is always in English. The translation into every desired language must first be provided by a translator. This is done using the Portable Object (<code>.po</code>) file format also used by GNU gettext. First, a PO template (<code>.pot</code>) file needs to be created. This can be done automatically via the Ant build script provided in the <code>sdk</code> directory of the GUI source code. The script should be copied to the plugin directory and modified by inserting the name of the plugin in the following line near the start of the file:<br />
<br />
<span style="color: #888">&lt;!-- Plugin name --&gt;</span><br />
<span style="color: #080">&lt;property</span> <span style="color: #800">name</span>=<span style="color: #008">"name"</span> <span style="color: #800">value</span>=<span style="color: #008">"''com.example.test''"</span><span style="color: #080">/&gt;</span><br />
<br />
After running Ant in the plugin directory, the newly created directory named <code>lang</code> should contain the translation template <code>com.example.test.pot</code> which looks like this:<br />
<br />
'''msgid''' <span style="color: #008">""</span><br />
'''msgstr''' <span style="color: #008">""</span><br />
<span style="color: #008">"Project-Id-Version: NAME<span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"POT-Creation-Date: 2009-01-01 12:34+0100<span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"PO-Revision-Date: DATE<span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"Last-Translator: NAME <span style="color: #080">&lt;EMAIL&gt;</span><span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"Language-Team: NAME <span style="color: #080">&lt;EMAIL&gt;</span><span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"MIME-Version: 1.0<span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"Content-Type: text/plain; charset=UTF-8<span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"Content-Transfer-Encoding: 8bit<span style="color: #808">\n</span>"</span><br />
<span style="color: #008">"Plural-Forms: nplurals=INTEGER; plural=EXPRESSION;<span style="color: #808">\n</span>"</span><br />
<br />
'''msgid''' <span style="color: #008">"Example"</span><br />
'''msgstr''' <span style="color: #008">""</span><br />
<br />
'''msgid''' <span style="color: #008">"Account"</span><br />
'''msgstr''' <span style="color: #008">""</span><br />
<br />
'''msgid''' <span style="color: #008">"Account settings"</span><br />
'''msgstr''' <span style="color: #008">""</span><br />
<br />
This file can be opened in a dedicated tool like [http://kbabel.kde.org KBabel] or [http://www.poedit.net/ Poedit], or in a simple text editor as long as it supports UTF-8. The translation of each <code>msgid</code> text is stored as the corresponding <code>msgstr</code> text. A German translation could look like this:<br />
<br />
'''msgid''' <span style="color: #008">"Example"</span><br />
'''msgstr''' <span style="color: #008">"Beispiel"</span><br />
<br />
'''msgid''' <span style="color: #008">"Account"</span><br />
'''msgstr''' <span style="color: #008">"Benutzerkonto"</span><br />
<br />
'''msgid''' <span style="color: #008">"Account settings"</span><br />
'''msgstr''' <span style="color: #008">"Kontoeinstellungen"</span><br />
<br />
The first <code>msgid</code> / <code>msgstr</code> pair is a special case. It contains an empty text as <code>msgid</code> and a header with meta-information as <code>msgstr</code>. This information is useful for maintaining multiple versions of multiple translations. The only entry which influences the actual translation is the last one, <code>Plural-Forms</code>. It specifies how to translate text which contains numbers. Unlike with the original GNU gettext tools, this entry is currently ''not'' optional in <code>.po</code> files used in the Open-Xchange GUI. The two placeholders <code>INTEGER</code> and <code>EXPRESSION</code> must be replaced with the number of plural forms and a rule for selecting the correct plural form for a number, respectively. A list of these values for most languages can be found in the [http://www.gnu.org/software/automake/manual/gettext/Plural-forms.html#index-plural-form-formulas-1059 GNU gettext manual]. For German this line would look like this:<br />
<br />
<span style="color: #008">"Plural-Forms: nplurals=2; plural=n != 1;<span style="color: #808">\n</span>"</span><br />
<br />
The translated file must be saved in the <code>lang</code> directory with the language ID as file name and <code>.po</code> as extension, e. g. <code>de_DE.po</code> for the German translation. The language ID usually consists of a lowercase two-letter language code and an uppercase two-letter country code, separated by an underscore.<br />
<br />
After saving the translated file and reloading the GUI, the configuration page of our plugin should appear translated when a translation for the current language is available, and appear in English when a translation could not be found.<br />
<br />
Whenever new user-visible strings are added to the plugin, the build script should be re-run to create an updated PO template, which can then be ''merged'' with the existing translations to include the new untranslated strings without throwing away the existing translations. The merging can be done either in one of the PO editors, or manually with the <code>msgmerge</code> tool:<br />
<br />
msgmerge -U lang/de_DE.po lang/com.example.test.pot<br />
<br />
== Widgets ==<br />
<br />
To do anything useful, our new configuration page needs some widgets. A widget is, in general, any visible UI element like an input field or a button. All widgets have some common methods and properties, which are defined in the abstract class <code>ox.UI.Widget</code>. Concrete widgets are members of direct or indirect subclasses of <code>ox.UI.Widget</code>. Intermediate subclasses add common functionality which is useful for many, but not all widgets. For example, <code>ox.UI.Container</code> adds the ability to contain other widgets. Our configuration page is a subclasses of <code>ox.UI.Container</code> and therefore we can add other widgets to it using the <code>addWidget</code> method, which it inherits from <code>ox.UI.Container</code>.<br />
<br />
The code to add widgets is placed in the <code>init</code> method of the configuration page. This method is called before the page is displayed for the first time. This is the preferred place to add widgets and perform other initialization, instead of the body of the plugin.<br />
<br />
page.init = '''function'''() {<br />
page.addWidget('''new''' ox.UI.Input(_(<span style="color: #008">"Mail address"</span>)), <span style="color: #008">"email"</span>);<br />
page.addWidget('''new''' ox.UI.Password(_(<span style="color: #008">"Password"</span>)), <span style="color: #008">"password"</span>);<br />
};<br />
<br />
<code>ox.UI.Input</code> is a simple text input field with a label. <code>ox.UI.Password</code> is a subclass of <code>ox.UI.Input</code> which does not display the entered password. Both constructors take the translated label as the only parameter. The created objects are passed as the first parameter to the method <code>addWidget</code> of the configuration page. This adds them to the page and automatically aligns the labels and the input fields:<br />
<br />
[[Image:PluginAPIWidgets.png|center|Test page]]<br />
<br />
== Communication with the server ==<br />
<br />
The second parameter to <code>addWidget</code> determines how the data of the added widget is handled by its parent container. When the user clicks on the Save button at the top of the window, the configuration page queries all its children and collects their data into a single object. In the example above, the second parameter is a string which specifies the field name in the composite object. When the user enters "user@example.com" as mail address and "secret" as password, the resulting object will be<br />
<br />
{ email: <span style="color: #008">"user@example.com"</span>, password: <span style="color: #008">"secret"</span> }<br />
<br />
To actually do something with the created object, we override the <code>save</code> method of the page:<br />
<br />
page.save = '''function'''(data, cont) {<br />
ox.JSON.put(AjaxRoot + <span style="color: #008">"/com.example.test?action=set&session="</span> + session,<br />
data, cont, handleErrors);<br />
}<br />
<br />
The method gets called when the page needs to be saved (either because the user clicked on the Save button or because the user is about to leave the page). Its two parameters are <code>data</code>, the object which contains the page's data, and <code>cont</code>, a continuation function which should be called once the data is saved successfully. If the continuation function is not called, the data will still be considered as not saved, i. e. the user will be asked to save the data before leaving the page.<br />
<br />
In the example above, the parameters are passed unmodified to the static method <code>ox.JSON.put</code>, which encodes the data as [http://json.org/ JSON] and sends it via an HTTP PUT request to the specified URL. Static methods for GET and POST requests are also available. The URL is constructed from the global variable <code>AjaxRoot</code>, which specifies the path of the Open-Xchange application server (usually <code>/ajax</code>), the name of a hypothetical Java servlet, and URL parameters which depend on the servlet. The URL parameter <code>session</code> should be present in every servlet request and contain the value of the global variable of the same name. This parameter is used to protect against [http://en.wikipedia.org/wiki/Cross-site_request_forgery XSRF] attacks.<br />
<br />
The reply from the server should conform to the general rules of the [https://documentation.open-xchange.com/ HTTP API], in particular, the error handling. If there are no errors, the reply is decoded and passed as an object to the specified callback function. In our case, that callback function is <code>cont</code>, which ignores any parameters and merely updates some internal state. If there are errors, the callback is not called. Instead, the error is decoded and displayed by default. If, as in the above example, a second callback function is specified as the optional fourth parameter to <code>ox.JSON.put</code> then it is called and given a chance to handle the error before or instead of displaying it. For our example this function handles the inevitable error which will occur when we try to access the non-existent servlet at <code>/ajax/com.example.test</code>:<br />
<br />
'''function''' handleErrors(result, status) {<br />
'''if''' (status == 404 || status == 405) {<br />
ox.Configuration.error(<br />
_(<span style="color: #008">"Please write and install a servlet named com.example.test"</span>));<br />
'''return''' '''true''';<br />
}<br />
<br />
There are two slightly different cases in which the error callback is called. When the server returns a properly formatted JSON reply with an error field as described in [https://documentation.open-xchange.com/ HTTP_API (Error handling)], the callback is called with the object which represents the entire server reply as the only parameter. When the server returns an HTTP status code other than 200, the error callback is called with the status text as the first parameter and the status code as the second parameter. In both cases, the error handler can return <code>true</code> to prevent the default error handling from displaying the error message. This is exactly what the <code>handleErrors</code> function does when the server returns an HTTP status 404 ("Not Found") or 405 ("Method Not Allowed"). As a general rule, error callbacks should only return <code>true</code> for specific known cases, and let the default error handling process any unknown errors.<br />
<br />
Besides uploading of entered settings, a typical configuration page will need to display the currently active settings. These can be displayed by overriding the <code>load</code> method of the page:<br />
<br />
page.load = '''function'''(cont) {<br />
ox.JSON.get(AjaxRoot + <span style="color: #008">"/com.example.test?action=get&session="</span> + session,<br />
'''function'''(reply) { cont(reply.data); }, handleErrors);<br />
}<br />
<br />
Similar to the <code>save</code> method, the <code>load</code> method takes a continuation function as parameter. The difference is that, this time, the data travels in the other direction: instead of getting the data ''from'' the plugin API as a parameter, the <code>load</code> method must pass the data as parameter ''to'' the plugin API's continuation function. In most cases, the reply received from the server will not be structured exactly like the data object defined by <code>addWidget</code> calls. Therefore, the continuation function can't be passed directly to <code>ox.JSON.get</code> like in the <code>save</code> method. Instead, an anonymous function is used to extract the data object from its <code>reply</code> parameter and call the continuation function with the extracted data as parameter. The function does not need to be anonymous, but it must be defined inside of the <code>load</code> method, to have access to <code>cont</code>.<br />
<br />
[[Category: OX6]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OX6:Gui_path&diff=22093OX6:Gui path2016-06-29T13:50:45Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>==== OX6 GUI settings ====<br />
This table shows a partial list of OX6 GUI settings. These settings are stored in a javascript object notation (JSON) which is directly computed by the GUI. Information about the used format can be found in the [https://documentation.open-xchange.com/ HTTP API ]. By default, this object does not existent upon user creation and is stored by the GUI after the first logout of the user. This object however can be manipulated through the RMI interface (as well as on the command line). It is not necessary to define all settings (inner objects), missing ones will be added by the GUI automatically. Please be very careful if you change the settings after it has been initialized and stored by the GUI, all existing settings will be lost because they will be overwritten! Please also take care the you use the correct format of that object, otherwise the user might not be able to login (e.g. on a missing comma or bracket). This article refers to the OX6 frontend settings, if your are looking for the AppSuite UI documentation please take a look here http://oxpedia.org/index.php?title=AppSuite:UI<br />
<br />
<br />
{| id="gui_path" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''Gui settings'''<br />
|-<br />
! name !! type !! value !! comment<br />
|-<br />
| infostore || Object || [[#infostore object|infostore object]] || infostore settings<br />
|-<br />
| mail || Object || [[#mail object|mail object]] || mail settings<br />
|-<br />
| portal || Object || [[#portal object|portal object]] || portal layout and content<br />
|- <br />
| global || Object || [[#global object|global object]] || timestamp settings and global settings<br />
|-<br />
| menu || Object || [[#menue object|menue object]] || menu iteration<br />
|-<br />
| theme || Object || [[#theme object|theme object]] || default theme and path<br />
|- <br />
| effects || Object || [[#effects object|effects object]] || hover and global effects<br />
|- <br />
| tasks || Object || [[#tasks objects|tasks objects]] || tasks settings <br />
|- <br />
| FolderTreeState || Object || [[#foldertree object|foldertree object]] || holds the folder tree state<br />
|-<br />
| contacts || Object || [[#contacts object|contacts object]] || contacts settings <br />
|-<br />
| calendar || Object || [[#calendar object|calendar object]] || calendar settings <br />
|-<br />
|}<br />
<br />
====Settings for the infostore module====<br />
This table contains the settings for the GUI's infostore<br />
{| id="infostore object" style="width:100%" cellspacing="0" border="1" align="bottom" <br />
|+'''infostore object'''<br />
|-<br />
! name !! type !! values !! comment<br />
|-<br />
| view || value || infostore/(list,split) || infostore view<br />
|}<br />
<br />
====Settings for the E-Mail module====<br />
This tables contains the settings for the E-Mail module.<br />
{| id="mail object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''mail object'''<br />
|-<br />
! name !! type !! values !! comment<br />
|-<br />
| auto_save_drafts || Number || 0,1,3,5,10,15,30|| time in minutes, 0 for disabled<br />
|-<br />
| htmlmessage || Boolean|| true,false || show email as html or plain text<br />
|-<br />
| signatures || Array || [[#signature objects|signature objects]] || array of signature objects<br />
|-<br />
| view || String || mail/(list,hsplit,vsplit)/unthreaded || mail view<br />
|-<br />
| view spam || String || mail/(list,hsplit,vsplit)/unthreaded || mail view for spam folder<br />
|-<br />
| autocomplete || Boolean || true,false || autocomplete functions<br />
|-<br />
| fullmailheader || Boolean || true,false || show complete mail header<br />
|-<br />
| notifyacknoledge ||Boolean || true,false || notify on read acknowledgment<br />
|-<br />
| newmail_options || Object || [[#newmail_options objects|newmail_options objects]] || object for the new email window settings<br />
|-<br />
| formatmessage || String || ALTERNATIVE,TEXT/HTML,TEXT/PLAIN || email format<br />
|}<br />
<br />
<br />
{| id="newmail_options objects" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''newmail_options objects'''<br />
! name !! type !! values !! comment<br />
|-<br />
| cc || Boolean || true,false || show cc input field<br />
|-<br />
| bcc || Boolean || true,false || show bcc input field<br />
|-<br />
| from || Boolean || true,false || show from input field<br />
|-<br />
| options || Boolean || true,false || show options field<br />
|- <br />
|}<br />
<br />
<br />
{| id="signature objects" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''signature objects'''<br />
! name !! type !! values !! comment<br />
|-<br />
| signature_name || String || name || signature name<br />
|-<br />
| position || String || below,above || where to show the signature in the mail text<br />
|-<br />
| signature_text || String || text || signature text<br />
|-<br />
| signature_default || Boolean || true,false || true only for the default signature<br />
|-<br />
|}<br />
<br />
====Start page settings====<br />
This table contains the possible settings for the start page.<br />
{| id="portal object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''portal object'''<br />
! name !! type !! values !! comment<br />
|-<br />
| externalcontents || Array || [[#externalcontents objects|externalcontents objects]] || array of external content objects (UWA widgeds)<br />
|-<br />
| minicalendar ||Boolean || true,false|| show minicalendar<br />
|-<br />
| internalcontents || Array || [[#internalcontens objects|internalcontents objects]] || array of internal content objects (groupware modules)<br />
|-<br />
| infobox || Boolean || true,false|| show infobox<br />
|-<br />
| tooltip ||Boolean ||true,false || show tooltip<br />
|-<br />
|}<br />
<br />
<br />
{| id="externalcontents objects" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''externalcontents objects'''<br />
! name !! type !! values !! comment<br />
|-<br />
| autorefresh || Boolean || true,false || enable autorefresh for the widget<br />
|-<br />
| title || String || name || widget title<br />
|-<br />
| standalone || Boolean || true,false || widget is standalone<br />
|-<br />
| visible || Boolean || true,false || widget is visible on the portal page<br />
|-<br />
| adj || Object || [[#adj object|adj object]] || position setting of the widget<br />
|-<br />
| url || String || url || widget url<br />
|-<br />
| parameter || Object || parameter object || widget parameters in an object<br />
|-<br />
| id || String || unique id || unique id for the widget<br />
|- <br />
|}<br />
<br />
<br />
{| id="internalcontens objects" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''internalcontens objects'''<br />
! name !! type !! values !! comment<br />
|-<br />
| params || Object || [[#params object|params object]] || widget parameter<br />
|-<br />
| header || Sting || E-Mail,Calendar,InfoStore,Tasks || header name<br />
|-<br />
| visible || Boolean || true,false || show module on the portal<br />
|-<br />
| adj || Object || [[#adj object|adj object]] || position setting of the widget<br />
|- <br />
| external || Boolean || false || only false is implemented<br />
|-<br />
| module || String || mail,calendar,infostore,tasks || internal module name<br />
|-<br />
|}<br />
<br />
<br />
{| id="adj object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''adj object'''<br />
! name !! type !! values !! comment<br />
|-<br />
| hw || Number || 0... || widget height relative to others, 0 for auto<br />
|-<br />
| ww || Number || 0... || widget width relative to others, 0 for auto<br />
|-columns<br />
| y || Number || 0... || vertical position on the start page in rows, 0 for auto<br />
|-<br />
| x || Number || 0... || horizontal position on the start page in columns, 0 for auto<br />
|-<br />
|}<br />
<br />
<br />
{| id="params object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''params object'''<br />
! name !! type !! values !! comment<br />
|-<br />
| limit || Number || 5,10,15,20 || number of shown items in the module<br />
|-<br />
|}<br />
<br />
====global settings====<br />
This table contains the global settings options<br />
{| id="global object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''global object'''<br />
|-<br />
! name !! type !! values !! comment<br />
|-<br />
| confirmtimestamp ||Number || Timestamp || timestamp for the last confirmed/declined appointment<br />
|-<br />
| confirmpopup || Boolean || true,false|| confirmation pop-up for new appointments<br />
|-<br />
| save || Number || 0,1,2 || save layout on logout: 0 no, 1 yes, 2 ask<br />
|-<br />
| autorefresh || Number || 0,5,10,15,30 || time in minutes for GUI autorefresh, 0 for never<br />
|-<br />
| region || Object || [[#region object|region object]] || region settings for time and date formats<br />
|-<br />
| private_categories || String || tag,tag,.. || comma separated list of user defined tags <br />
|}<br />
<br />
<br />
{| id="region object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''region object'''<br />
|-<br />
! name !! type !! values !! Comment<br />
|-<br />
| time || Object || [[#time object|time object]] || object for time defaults<br />
|-<br />
| date || Object || [[#date object|date object]] || object for date defaults<br />
|-<br />
|}<br />
<br />
<br />
{| id="time object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''time object'''<br />
|-<br />
! name !! type !! values !! Comment<br />
|-<br />
| predefined || Number || 0,1 || 0 user defined, 1 language depending<br />
|-<br />
| format || String || HH:mm,"hh:mm a" || a stands for suffix which needs to be true then, too. m is 0-59, mm is 00-59, H is 1-24, HH is 01-24, h is 1-12, hh is 01-12, a is AM/PM.<br />
|-<br />
| format_hour || String || "hh a",HH || a stands for suffix which needs to be true then, too. H is 1-24, HH is 01-24, h is 1-12, hh is 01-12, a is AM/PM.<br />
|-<br />
| format_suffix || Boolean || true,false || add suffix<br />
|-<br />
|}<br />
<br />
<br />
{| id="date object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''date object'''<br />
|-<br />
! name !! type !! values !! Comment<br />
|-<br />
| format_selected_index || Number || id from [[#index|index]] || preselection for the user time format drop down<br />
|-<br />
| separator || String || /,.,- || date separator<br />
|-<br />
| predifined || Number || 0,1 || 0 user defined, 1 language depending<br />
|-<br />
| format || String || value from [[#index|index]] || date format <br />
|-<br />
|}<br />
<br />
<br />
{| id="index" style="width:50%" cellspacing="0" border="1" align="bottom"<br />
|+'''date index'''<br />
|-<br />
! id !! value<br />
|-<br />
| 0 || M/d/yyyy<br />
|-<br />
| 1 || M/d/yy<br />
|-<br />
| 2 || MM/dd/yy<br />
|-<br />
| 3 || MM/dd/yyyy<br />
|-<br />
| 4 || yy/MM/dd<br />
|-<br />
| 5 || dd/MM/yyyy<br />
|-<br />
| 6 || dd/MM/yy<br />
|-<br />
| 7 || dd.MM.yyyy<br />
|-<br />
| 8 || dd.MM.yy<br />
|-<br />
| 9 || d.MM.yy<br />
|-<br />
| 10 || d.M.yy<br />
|-<br />
| 11 || d.M.yyyy<br />
|-<br />
| 12 || yyyy-MM-dd<br />
|-<br />
| 13 || dd-MMM-yy<br />
|-<br />
|}<br />
<br />
===menuiteration===<br />
This object holds the setting of the pannel <br />
{| id="menue object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''menue object'''<br />
|-<br />
! name !! type !! values !! Comment<br />
|-<br />
| menuiteration || Number || 1,2,3,4,5,6 || highs of the GUI pannel in rows <br />
|-<br />
|}<br />
<br />
===theme settings===<br />
This table shows the setting for the default theme<br />
{| id="theme object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''theme object'''<br />
|-<br />
! name !! type !! values !! Comment<br />
|-<br />
| name || String || <theme name> || name of the default theme <br />
|-<br />
| path ||String || <theme path> || path to the default theme<br />
|-<br />
|}<br />
<br />
===effects object===<br />
the effects object holds the settings for GUI effects like hovers and fading.<br />
{| id="effects object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''effects object'''<br />
|-<br />
! name !! type !! values !! Comment<br />
|-<br />
| global || Boolean || true,false || enable effects<br />
|-<br />
| hover || Object || [[#hover object|hover object]] || includes hover settings for the modules<br />
|-<br />
| fading|| Boolean || true,false || fading<br />
|-<br />
|}<br />
<br />
<br />
{| id="hover object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''hover object'''<br />
|-<br />
! name !! type !! values !! Comment<br />
|-<br />
| speed || Number || 1,2,3 || hover delay, 1 short, 2 normal, 3 long<br />
|-<br />
| calendar || Boolean || true,false || hover for calendar<br />
|-<br />
| contacts || Boolean || true,false || hover for contacts<br />
|-<br />
| portal || Boolean || true,false || hovers on the portal page<br />
|- <br />
| infostore || Boolean || true,false || hover for infostore<br />
|-<br />
| mail || Boolean || true,false || hover for mail <br />
|-<br />
| tasks || Boolean || true,false || hover for tasks<br />
|-<br />
|}<br />
<br />
===setting for tasks===<br />
This objects holds the settings for tasks<br />
{| id="tasks objects" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''tasks objects'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| interval || Number || 5,10,15,20,30,60 || interval for reminder<br />
|-<br />
| gridsort || String || asc || how tasks get sorted<br />
|-<br />
| view || String || tasks/(split,list) || task view<br />
|-<br />
|}<br />
<br />
===foldertree object===<br />
this is an internal gui object to store the folder tree on logout. This<br />
object should not be modified.<br />
{| id="foldertree object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''foldertree object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| FolderTreeState || Object || foldertree object || folder tree state on GUI logout, you should not touch <br />
|-<br />
|}<br />
<br />
<br />
===Settings for contacts===<br />
the contacts object holds the settings for the contacts.<br />
{| id="contacts object" style="width:100%" cellspacing="0" border="1" align="bottom"<br />
|+'''contacts object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| gridsort ||String || asc || Sorting of contacts<br />
|-<br />
| cardsToViewPerColumn || String || auto,4,5,6,7|| displayed cards per column <br />
|-<br />
| view || String || contacts/(cards,phonelist) || card view<br />
|-<br />
|}<br />
<br />
===settings for the calendar===<br />
The calendar object stores the settings for the calendar.<br />
{| id="calendar object" style="width:100%" cellspacing="0" border="1" align="bottom" <br />
|+'''calendar object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| workweek ||Object || [[#workweek object|workweek object]] || settings for the workweek <br />
|-<br />
| endtime || Number || 0..23 || calendar display end time in hours<br />
|-<br />
| teams || Array || [[#teams object|teams object]] || Array of teams<br />
|-<br />
| allfolders ||Boolean || true,false || activate "Show all my appointments from all calendars"<br />
|-<br />
| starttime || Number || 0..23 || calendar display end time in hours<br />
|-<br />
| interval || Number || 5,10,15,20,30,60 || calendar resolution<br />
|-<br />
| day || Object || [[#day object|day object]] || settings for day view <br />
|-<br />
| view || String || calendar/(calendar,team,list)/(day,workweek,month,week,custom,) || Calendar view, for team, groupware functionality must be available. '''Deprecated''', see views.<br />
|-<br />
| views || Object || [[#views object|views object]] || default calendar views<br />
|-<br />
| custom || Object || [[#custom object|custom object]] || setting for the custom view<br />
|-<br />
|}<br />
<br />
<br />
{| id="workweek object" style="width:100%" cellspacing="0" border="1" align="bottom" <br />
|+'''workweek object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| countdays || Number || 1,2,3,4,5,6,7 || Number of days in work week<br />
|-<br />
| numberofappointments || Number || 1,2,3,4,5,6,7,8 || Number of concurrent appointments shown in workweek view<br />
|-<br />
| startday || Number || 0,1,2,3,4,5,6 || 0 Sunday,...,6 Saturday <br />
|-<br />
|}<br />
<br />
<br />
{| id="day object" style="width:100%" cellspacing="0" border="1" align="bottom" <br />
|+'''day object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| numberofappointments || Number || 1,2,3,4,5,6,7,8 || Number of concurrent appointments shown in day view<br />
|-<br />
|}<br />
<br />
<br />
{| id="views object" style="width: 100%" cellspacing="0" border="1" align="bottom"<br />
|+'''views object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| shared || Boolean || true, false || Whether all views share the same default time range or not.<br />
|-<br />
| view || String || "calendar", "team", "list" || Default view.<br />
|-<br />
| calendar || String || "day", "workweek", "month", "week", "custom" || Default time range for the calendar view.<br />
|-<br />
| team || String || "day", "workweek", "month", "week", "custom" || Default time range for the team view.<br />
|-<br />
| list || String || "day", "workweek", "month", "week", "custom" || Default time range for the list view.<br />
|-<br />
|}<br />
<br />
<br />
{| id="custom object" style="width:100%" cellspacing="0" border="1" align="bottom" <br />
|+'''custom object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| numberofappointments || Number || 1,2,3,4,5,6,7,8 || Number of concurrent appointments shown in day view<br />
|-<br />
| countdays || Number || 1,2,3,4,5,6,7 || Number of days in work week<br />
|-<br />
|}<br />
<br />
<br />
{| id="teams object" style="width:100%" cellspacing="0" border="1" align="bottom" <br />
|+'''teams object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| team_default || Boolean || true,false || true for the default team<br />
|-<br />
| name || string || name || name for the team<br />
|-<br />
| children || Array || [[#children objects|children objects]] || Array of children objects, childrens are users that belong to the team<br />
|- <br />
|}<br />
<br />
<br />
{| id="children objects" style="width:100%" cellspacing="0" border="1" align="bottom" <br />
|+'''children object'''<br />
! name !! type !! values !! Comment<br />
|-<br />
| id || Number || userid || user id of the team member<br />
|-<br />
| display _name || String || display name || display name of the team member<br />
|-<br />
| type || Number || 1 || only 1 implemented<br />
|-<br />
|}<br />
<br />
===example /path, saved from a fresh user directly after the first login/logout===<br />
/path={"calendar":{"view":"calendar/calendar/day","day":{"numberofappointments":4},"workweek":{"countdays":5,"startday":1,"numberofappointments":2},"starttime":8,"allfolders":true,"custom":{"countdays":3,"numberofappointments":3},"endtime":18,"interval":30},"FolderTreeState":{"folder_tree$1":{"folder_tree$default":{"folder_tree$default.INBOX":{}},"folder_tree$25":{}},"folder_tree$9":{"folder_tree$10":{"folder_tree$28":{}}}},"contacts":{"view":"contacts/cards","cardsToViewPerColumn":"auto","gridsort":"asc"},"theme":{"path":"default","name":"Default"},"portal":{"infobox":true,"internalcontents":[{"params":{"limit":5},"header":"E-Mail","visible":true,"adj":{"hw":1,"ww":1,"y":0,"x":1},"external":false,"module":"mail"},{"params":{"limit":5},"header":"Calendar","visible":true,"adj":{"hw":1,"ww":1,"y":0,"x":0},"external":false,"module":"calendar"},{"params":{"limit":5},"header":"InfoStore","visible":true,"adj":{"hw":1,"ww":1,"y":1,"x":0},"external":false,"module":"infostore"},{"params":{"limit":5},"header":"Tasks","visible":true,"adj":{"hw":1,"ww":1,"y":1,"x":1},"external":false,"module":"tasks"}],"tooltip":false,"externalcontents":[],"minicalendar":true},"infostore":{"view":"infostore/split"},"effects":{"hover":{"calendar":true,"speed":2,"contacts":true,"portal":true,"infostore":true,"mail":true,"tasks":true},"global":false,"fading":false},"mail":{"newmail_options":{"cc":true,"bcc":false,"from":true,"options":false},"view":"mail/hsplit/unthreaded","formatmessage":"ALTERNATIVE","notifyacknoledge":true,"autocomplete":true,"auto_save_drafts":3,"signatures":[],"fullmailheader":true,"htmlmessage":true},"tasks":{"view":"tasks/split","gridsort":"asc","interval":30},"menu":{"menuiteration":4},"private_categories":"","global":{"autorefresh":10,"save":1,"confirmtimestamp":1216928454103,"confirmpopup":true}}<br />
<br />
for example, here is how it would work on the command line:<br />
/opt/open-xchangen/sbin/changeuser -c 71 -i 5 --addguipreferences \<br />
'/gui={"calendar":{"view":"calendar/calendar/day","day":{"numberofappointments":4},\<br />
"workweek":{"countdays":5,"startday":1,"numberofappointments":2},"starttime":8,"allfolders":true,\ <br />
"custom":{"countdays":3,"numberofappointments":3},"endtime":18,"interval":30},\ <br />
"FolderTreeState":{"folder_tree$1":{"folder_tree$default":{"folder_tree$default.INBOX":{}},\ <br />
"folder_tree$25":{}},"folder_tree$9":{"folder_tree$10":{"folder_tree$28":{}}}},\ <br />
"contacts":{"view":"contacts/cards","cardsToViewPerColumn":"auto","gridsort":"asc"},\ <br />
"theme":{"path":"default","name":"Default"},\ "portal":{"infobox":true,\ <br />
"internalcontents":[{"params":{"limit":5},"header":"E-Mail","visible":true,\ <br />
"adj":{"hw":1,"ww":1,"y":0,"x":1},"external":false,"module":"mail"},\ <br />
{"params":{"limit":5},"header":"Calendar","visible":true,\ <br />
"adj":{"hw":1,"ww":1,"y":0,"x":0},\ "external":false,"module":"calendar"},\ <br />
{"params":{"limit":5},"header":"InfoStore","visible":true,\ <br />
"adj":{"hw":1,"ww":1,"y":1,"x":0},"external":false,"module":"infostore"},\ <br />
{"params":{"limit":5},"header":"Tasks","visible":true,\ <br />
"adj":{"hw":1,"ww":1,"y":1,"x":1},"external":false,"module":"tasks"}],\ <br />
"tooltip":false,"externalcontents":[],"minicalendar":true},\ <br />
"infostore":{"view":"infostore/split"},\ <br />
"effects":{"hover":{"calendar":true,"speed":2,"contacts":true,\ <br />
"portal":true,"infostore":true,"mail":true,"tasks":true},\ <br />
"global":false,"fading":false},\ <br />
"mail":{"newmail_options":{"cc":true,"bcc":false,"from":true,"options":false},\ <br />
"view":"mail/hsplit/unthreaded","formatmessage":"ALTERNATIVE",\ <br />
"notifyacknoledge":true,"autocomplete":true,"auto_save_drafts":3,\ <br />
"signatures":[],"fullmailheader":true,"htmlmessage":true},\ <br />
"tasks":{"view":"tasks/split","gridsort":"asc","interval":30},\ <br />
"menu":{"menuiteration":4},"private_categories":"",\ <br />
"global":{"autorefresh":10,"save":1,"confirmtimestamp":1216928454103,\ <br />
"confirmpopup":true}}'<br />
<br />
[[Category: OX6]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Automatic_Delete_OXObjects_Per_User&diff=22092Automatic Delete OXObjects Per User2016-06-29T13:48:57Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div><div class="title">How to automatically delete all objects of one user</div><br />
<br />
I just wrote the following quick&dirty hack to delete all objects and folders created by an OXHE User. It can be useful to clean up a context or to just delete all data from one user. The following JAVA file contains the logic which is needed to login/search/delete via the Open-Xchange [https://documentation.open-xchange.com/ HTTP API].<br />
<br />
<pre><br />
package com.openexchange.tools.cleaner;<br />
<br />
import java.io.IOException;<br />
import java.util.logging.Level;<br />
import java.util.logging.Logger;<br />
import org.apache.commons.httpclient.HttpClient;<br />
import org.apache.commons.httpclient.HttpException;<br />
import org.apache.commons.httpclient.methods.GetMethod;<br />
import org.apache.commons.httpclient.methods.PostMethod;<br />
import org.apache.commons.httpclient.methods.PutMethod;<br />
import org.apache.commons.httpclient.methods.RequestEntity;<br />
import org.apache.commons.httpclient.methods.StringRequestEntity;<br />
import org.apache.commons.httpclient.protocol.Protocol;<br />
import org.apache.commons.logging.Log;<br />
import org.apache.commons.logging.LogFactory;<br />
import org.json.JSONArray;<br />
import org.json.JSONException;<br />
import org.json.JSONObject;<br />
<br />
/**<br />
*<br />
* @author cutmasta<br />
*/<br />
public class Start {<br />
<br />
Log LOG = LogFactory.getLog(Start.class);<br />
private SessionObject so = null;<br />
private String username = null;<br />
private String password = null;<br />
private String host = "localhost";<br />
private String protocol = "http";<br />
private static String CONTENT_TYPE_JSCRIPT = "text/javascript";<br />
private static String CHARSET_JSCRIPT = "UTF-8";<br />
private String TASK_SEARCH = "tasks";<br />
private String CONTACT_SEARCH = "contacts";<br />
private String CALENDAR_SEARCH = "calendar";<br />
private String INFOSTORE_SEARCH = "infostore";<br />
<br />
public static void main(String[] args) {<br />
new Start(args);<br />
}<br />
<br />
private Start(String[] args) {<br />
<br />
if (args.length != 4) {<br />
LOG.info("Arguments needed: <host> <protocol> <username> <password>");<br />
LOG.info("Example: test.org https test@sp4.com test");<br />
exitApp();<br />
}<br />
<br />
host = args[0].trim();<br />
protocol = args[1].trim();<br />
username = args[2].trim();<br />
password = args[3].trim();<br />
<br />
if (protocol.equals("https")) {<br />
Protocol easyhttps = new Protocol("https", new EasySSLProtocolSocketFactory(), 443);<br />
Protocol.registerProtocol("https", easyhttps);<br />
}<br />
<br />
doLogin();<br />
<br />
try {<br />
<br />
// search all modules and fetch the id arrays<br />
doSearch();<br />
} catch (IOException ex) {<br />
LOG.error(ex);<br />
} catch (JSONException ex) {<br />
LOG.error("Error in process", ex);<br />
}<br />
<br />
<br />
}<br />
<br />
public String getSessionID() {<br />
return getSessionObject().getSessionid();<br />
}<br />
<br />
public SessionObject getSessionObject() {<br />
return so;<br />
}<br />
<br />
public String getUsername() {<br />
return username;<br />
}<br />
<br />
public String getPassword() {<br />
return password;<br />
}<br />
<br />
public String getHost() {<br />
return host;<br />
}<br />
<br />
private void doDeleteCreatedFolders(JSONArray rootfolders, String timestamp) throws JSONException, IOException {<br />
<br />
/* <br />
* In this method here we delete all folders <br />
* <br />
*/<br />
<br />
<br />
// loop through all root folders<br />
for (int i = 0; i < rootfolders.length(); i++) {<br />
<br />
// for each root/system folder , loop and delete its subfolders<br />
JSONObject subfolders_of_rootfolder_response = doGetSubFolders(rootfolders.getJSONArray(i).getInt(0));<br />
JSONArray subfolders_of_rootfolder = subfolders_of_rootfolder_response.getJSONArray("data"); <br />
for (int b = 0; b < subfolders_of_rootfolder.length(); b++) {<br />
JSONArray tmp_folder = subfolders_of_rootfolder.getJSONArray(b);<br />
if (!tmp_folder.getString(0).equalsIgnoreCase("default")) {<br />
LOG.debug("Deleting recursive all private folders with array: " + tmp_folder);<br />
deleteRecursiveFolder(tmp_folder);<br />
}<br />
}<br />
<br />
}<br />
<br />
<br />
<br />
}<br />
<br />
/**<br />
* This delete the subfolders of the given folder and the folder itself!<br />
* @param my_private_folder_array<br />
* @throws java.io.IOException<br />
* @throws org.json.JSONException<br />
*/<br />
private void deleteRecursiveFolder(JSONArray my_private_folder_array) throws IOException, JSONException {<br />
<br />
JSONObject my_private_subfolders_response = doGetSubFolders(my_private_folder_array.getInt(0));<br />
<br />
// only delete if subfolders exists<br />
//if (my_private_subfolders_response.length() > 0) {<br />
if (my_private_subfolders_response.getJSONArray("data").length() > 0) {<br />
<br />
LOG.debug(my_private_subfolders_response);<br />
<br />
JSONArray my_private_subfolders = my_private_subfolders_response.getJSONArray("data");<br />
<br />
String my_private_subfolders_timestamp = my_private_subfolders_response.getString("timestamp");<br />
<br />
//LOG.info("Private folders list: " +my_private_subfolders);<br />
for (int i = 0; i < my_private_subfolders.length(); i++) {<br />
JSONArray folder_data = my_private_subfolders.getJSONArray(i);<br />
LOG.debug("Deleting folder with ID " + folder_data.getInt(0) + " and parent ID " + folder_data.getInt(1) + " - Tstamp " + my_private_subfolders_timestamp);<br />
doDeleteFolder(folder_data.getInt(0), folder_data.getInt(1), my_private_subfolders_timestamp);<br />
}<br />
}<br />
<br />
<br />
/* Now delete the folder itself , which could contain the subfolders before!<br />
* We must "get" the folder data because we need the correct timestamp for deleting!<br />
*/<br />
JSONObject top_level_folder_data = doGetSingleFolder(my_private_folder_array.getInt(0));<br />
if(!my_private_folder_array.isNull(0) && !my_private_folder_array.isNull(1) && !top_level_folder_data.isNull("timestamp")){<br />
// execute delete<br />
doDeleteFolder(my_private_folder_array.getInt(0), my_private_folder_array.getInt(1), top_level_folder_data.getString("timestamp"));<br />
} <br />
<br />
<br />
<br />
}<br />
<br />
private void doDeleteFolder(int folder_id, int parent_id, String tstamp) {<br />
<br />
try {<br />
<br />
PutMethod deleteMethod = new PutMethod(getProtocol() + "://" + getHost() + "/ajax/folders?action=delete&timestamp=" + tstamp + "&session=" + getSessionObject().getSessionid());<br />
<br />
RequestEntity data = new StringRequestEntity("[" + folder_id + "]", CONTENT_TYPE_JSCRIPT, CHARSET_JSCRIPT);<br />
deleteMethod.setRequestEntity(data);<br />
getSessionObject().getOxClient().executeMethod(deleteMethod);<br />
<br />
JSONObject responseObject = ResponseTools.reponse2JsonObject(deleteMethod);<br />
<br />
LOG.debug("Delete folder response is: " + responseObject);<br />
<br />
} catch (Exception ex) {<br />
LOG.error("Error deleting folder with ID " + folder_id + " and parent ID " + parent_id, ex);<br />
}<br />
}<br />
<br />
private JSONObject doGetSubFolders(int parent_folder) throws IOException, JSONException {<br />
<br />
// 1 = id<br />
// 20 = Object ID of the parent folder.<br />
// 300 = Name of this folder.<br />
// 301 = Name of the module which implements this folder.<br />
// 302 = type // 1 private<br />
//2 public<br />
//3 shared<br />
// 5 system folder<br />
// 304 = true if this folder has subfolders.<br />
// 305 = own_rights<br />
<br />
try {<br />
<br />
<br />
GetMethod folder_search = new GetMethod(getProtocol() + "://" + getHost() + "/ajax/folders?action=list&columns=1,20,300,301,302,304,305&parent=" + parent_folder + "&session=" + getSessionObject().getSessionid());<br />
<br />
<br />
getSessionObject().getOxClient().executeMethod(folder_search);<br />
<br />
JSONObject responseObject = ResponseTools.reponse2JsonObject(folder_search);<br />
<br />
return responseObject;<br />
<br />
} catch (IOException ex) {<br />
LOG.error("Generic IO error while searching folders", ex);<br />
throw ex;<br />
} catch (JSONException ex) {<br />
LOG.error("JSON error while searching folders", ex);<br />
throw ex;<br />
}<br />
}<br />
<br />
private JSONObject doGetSingleFolder(int folder_id) throws IOException, JSONException {<br />
<br />
// 1 = id<br />
// 20 = Object ID of the parent folder.<br />
// 300 = Name of this folder.<br />
// 301 = Name of the module which implements this folder.<br />
// 302 = type // 1 private<br />
//2 public<br />
//3 shared<br />
// 5 system folder<br />
// 304 = true if this folder has subfolders.<br />
// 305 = own_rights<br />
<br />
try {<br />
<br />
<br />
GetMethod folder_search = new GetMethod(getProtocol() + "://" + getHost() + "/ajax/folders?action=get&id=" + folder_id + "&columns=1,20,300,301,302,304,305&session=" + getSessionObject().getSessionid());<br />
<br />
<br />
getSessionObject().getOxClient().executeMethod(folder_search);<br />
<br />
JSONObject responseObject = ResponseTools.reponse2JsonObject(folder_search);<br />
<br />
return responseObject;<br />
<br />
} catch (IOException ex) {<br />
LOG.error("Generic IO error while searching folders", ex);<br />
throw ex;<br />
} catch (JSONException ex) {<br />
LOG.error("JSON error while searching folders", ex);<br />
throw ex;<br />
}<br />
}<br />
<br />
private void doLogin() {<br />
<br />
LOG.info("Using " + getProtocol() + "://" + getUsername() + "@" + getHost() + " for connections!");<br />
<br />
HttpClient client = new HttpClient();<br />
<br />
<br />
PostMethod login_post = new PostMethod(getProtocol() + "://" + getHost() + "/ajax/login?action=login");<br />
login_post.addParameter("name", getUsername());<br />
login_post.addParameter("password", getPassword());<br />
<br />
try {<br />
<br />
client.executeMethod(login_post);<br />
<br />
JSONObject loginObject = ResponseTools.reponse2JsonObject(login_post);<br />
<br />
if (loginObject.has("session")) {<br />
so = new SessionObject();<br />
getSessionObject().setCookies(client.getState().getCookies());<br />
getSessionObject().setSessionid((String) loginObject.get("session"));<br />
getSessionObject().setOxClient(client);<br />
LOG.info("Login successfull!");<br />
} else {<br />
String errmsg = (String) loginObject.get("error");<br />
LOG.info("Error login into system!\n" + errmsg);<br />
exitApp();<br />
}<br />
} catch (Exception exp) {<br />
LOG.error("LOGIN ERROR", exp);<br />
} finally {<br />
login_post.releaseConnection();<br />
}<br />
}<br />
<br />
private void doSearch() throws JSONException, IOException {<br />
<br />
LOG.info("Starting search for objects...");<br />
<br />
JSONObject task_objects = doSearchInModule(TASK_SEARCH);<br />
JSONObject contact_objects = doSearchInModule(CONTACT_SEARCH);<br />
JSONObject calendar_objects = doSearchInModule(CALENDAR_SEARCH);<br />
JSONObject store_objects = doSearchInModule(INFOSTORE_SEARCH);<br />
<br />
LOG.info("Search done!");<br />
<br />
//LOG.info("Found " + task_objects.getJSONArray("data").length() + " task items");<br />
//LOG.info("Found " + contact_objects.getJSONArray("data").length() + " contact items");<br />
//LOG.info("Found " + calendar_objects.getJSONArray("data").length() + " calendar items");<br />
//LOG.info("Found " + store_objects.getJSONArray("data").length() + " infostore items");<br />
<br />
LOG.info("Starting delete process...");<br />
<br />
doDeleteMultiple(task_objects, contact_objects, calendar_objects, store_objects);<br />
<br />
LOG.info("Deleting Objects done!");<br />
<br />
<br />
LOG.info("Starting delete process for folders...");<br />
<br />
// search all folders and delete them<br />
JSONObject rootfolders_response = doGetRootFolders();<br />
<br />
JSONArray rootfolders = rootfolders_response.getJSONArray("data");<br />
<br />
doDeleteCreatedFolders(rootfolders, rootfolders_response.getString("timestamp"));<br />
<br />
LOG.info("Deleting folders done!");<br />
<br />
}<br />
<br />
private JSONArray buildDeleteArray(JSONObject module_objects, String MODULE) throws JSONException {<br />
<br />
JSONArray dat_array = new JSONArray();<br />
<br />
LOG.debug("Building delete array from json object: " + module_objects);<br />
<br />
if (module_objects.has("data") && module_objects.has("timestamp")) {<br />
<br />
String tstamp = module_objects.getString("timestamp");<br />
JSONArray srv_data_ids = module_objects.getJSONArray("data");<br />
for (int i = 0; i < srv_data_ids.length(); i++) {<br />
JSONArray ids = (JSONArray) srv_data_ids.get(i);<br />
JSONObject js = new JSONObject();<br />
js.put("module", MODULE);<br />
js.put("timestamp", tstamp);<br />
js.put("action", "delete");<br />
<br />
<br />
<br />
JSONObject del_ids = new JSONObject();<br />
del_ids.put("id", ids.getInt(0));<br />
del_ids.put("folder", ids.getInt(1));<br />
<br />
// workaround because infostore expects an array with a 1 json object which contains the ids<br />
if (MODULE.equals(INFOSTORE_SEARCH)) {<br />
// send array with object<br />
JSONArray tmp = new JSONArray();<br />
tmp.put(del_ids);<br />
js.put("data", tmp);<br />
} else {<br />
// send normal id <br />
js.put("data", del_ids);<br />
}<br />
dat_array.put(js);<br />
}<br />
}<br />
<br />
<br />
return dat_array;<br />
}<br />
<br />
private void doDeleteMultiple(JSONObject task_objects, JSONObject contact_objects, JSONObject calendar_objects, JSONObject store_objects) throws JSONException {<br />
<br />
LOG.info("Deleting tasks...");<br />
fireDeleteMultiple(buildDeleteArray(task_objects, TASK_SEARCH));<br />
LOG.info("Deleting contacts...");<br />
fireDeleteMultiple(buildDeleteArray(contact_objects, CONTACT_SEARCH));<br />
LOG.info("Deleting appointments...");<br />
fireDeleteMultiple(buildDeleteArray(calendar_objects, CALENDAR_SEARCH));<br />
LOG.info("Deleting infostore objects...");<br />
fireDeleteMultiple(buildDeleteArray(store_objects, INFOSTORE_SEARCH));<br />
}<br />
<br />
private JSONObject doGetRootFolders() throws IOException, JSONException {<br />
<br />
// 1 = id<br />
// 20 = Object ID of the parent folder.<br />
// 300 = Name of this folder.<br />
// 301 = Name of the module which implements this folder.<br />
// 302 = type // 1 private<br />
//2 public<br />
//3 shared<br />
// 5 system folder<br />
// 304 = true if this folder has subfolders.<br />
// 305 = own_rights<br />
<br />
try {<br />
<br />
<br />
GetMethod folder_search = new GetMethod(getProtocol() + "://" + getHost() + "/ajax/folders?action=root&columns=1,20,300,301,302,304,305&session=" + getSessionObject().getSessionid());<br />
<br />
<br />
getSessionObject().getOxClient().executeMethod(folder_search);<br />
<br />
return ResponseTools.reponse2JsonObject(folder_search);<br />
<br />
} catch (IOException ex) {<br />
LOG.error("Generic IO error while searching folders", ex);<br />
throw ex;<br />
} catch (JSONException ex) {<br />
LOG.error("JSON error while searching folders", ex);<br />
throw ex;<br />
}<br />
<br />
<br />
<br />
<br />
<br />
<br />
}<br />
<br />
private void fireDeleteMultiple(JSONArray del_data_array) {<br />
<br />
try {<br />
<br />
//LOG.info("Sending delete array: " + del_data_array);<br />
<br />
PutMethod deleteMethod = new PutMethod(getProtocol() + "://" + getHost() + "/ajax/multiple?continue=true&session=" + getSessionObject().getSessionid());<br />
<br />
RequestEntity data = new StringRequestEntity(del_data_array.toString(), CONTENT_TYPE_JSCRIPT, CHARSET_JSCRIPT);<br />
deleteMethod.setRequestEntity(data);<br />
getSessionObject().getOxClient().executeMethod(deleteMethod);<br />
<br />
JSONArray responseObject = ResponseTools.reponse2JsonArray(deleteMethod);<br />
<br />
//LOG.info(responseObject);<br />
<br />
} catch (Exception ex) {<br />
LOG.error("Error deleting items", ex);<br />
}<br />
}<br />
<br />
private JSONObject doSearchInModule(String MODULE) {<br />
<br />
// FETCH ALL OBJECT IDS FROM ALL FOLDERS <br />
// EXCLUDING PUBLIC ADRESSBOOK WHICH HAS ID 6 <br />
PutMethod searchMethod = new PutMethod(getProtocol() + "://" + getHost() + "/ajax/" + MODULE + "?action=search&columns=1,20&session=" + getSessionObject().getSessionid());<br />
<br />
try {<br />
<br />
RequestEntity data = new StringRequestEntity("{\"pattern\":\"*\"}", CONTENT_TYPE_JSCRIPT, CHARSET_JSCRIPT);<br />
searchMethod.setRequestEntity(data);<br />
getSessionObject().getOxClient().executeMethod(searchMethod);<br />
<br />
return ResponseTools.reponse2JsonObject(searchMethod);<br />
} catch (Exception ex) {<br />
LOG.error("Error searching " + MODULE, ex);<br />
return null;<br />
}<br />
}<br />
<br />
private void exitApp() {<br />
System.exit(1);<br />
}<br />
<br />
public String getProtocol() {<br />
return protocol;<br />
}<br />
}<br />
</pre><br />
<br />
[[Category: OX6]] [[Category:Quick hack]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Hosting_FAQ_for_System_Integrators&diff=22091Hosting FAQ for System Integrators2016-06-29T13:47:53Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>'''Q: Where can i get access to productive software packages for the hosting environment?'''<br><br />
A: Packages for download are available in the [http://oxpedia.org/index.php?title=Main_Page_HESE#quickinstall Open-Xchange Packages]<br />
<br />
'''Q: Where can i get further assistance in case of installation/integration questions?'''<br><br />
A: A forum for discussions is available on our [http://www.open-xchange.com/forum/ web site]<br />
<br />
'''Q: How can i integrate into existing LDAP services?'''<br><br />
A: The users and groups can be synced into OX through the commandline tools. The authentication can be done online through a LDAP authentication module<br />
<br />
'''Q: Is there a administration frontend to create and manage contexts, users, groups, resources?'''<br><br />
A: Provisioning of all objects (contexts, users, ...) can be very flexible done through the command line tools and the Java RMI interface. This interfaces can also be used for synchronisation with existing user databases and directories.<br />
<br />
Administering groups and resources will be possible within the webfrontend with the next build.<br />
<br />
Administration front ends for In-House deployments will follow soon.<br />
<br />
'''Q: Where are the mails stored in the Open-Xchange server?'''<br><br />
A: The Open-Xchange server has no own email server included. The Open-Xchange server does access mailboxes from existing systems. Please have a look at our [http://www.open-xchange.com/fileadmin/user_upload/open-xchange/document/whitepaper/OX-Hosted-Architecture.pdf architecture white paper].<br />
<br />
'''Q: What are the supported IMAP servers?'''<br><br />
A: Currently, Cyrus, Dovecot and Courier are the supported IMAP servers. This is described in more detail in the installation manual.<br />
<br />
'''Q: How can i create user objects (appointments,tasks,infostore items, pre defined UWA widgets) form extern for a customer?'''<br><br />
A: you can use the JSON [https://documentation.open-xchange.com/ HTTP API] used by the gui, a example is to be found here: [[Adding a pre defined UWA widget for a User]]<br />
<br />
'''Q: What are UWA widgets for?'''<br><br />
A: a description can be found in the Wiki on the [[Hyperion UWA]] page<br />
<br />
'''Q: What APIs are available?'''<br><br />
A: The APIs are to be found under [[Main_Page#Interfaces|Interfaces]] in this wiki<br />
<br />
'''Q: Do i need to set module access for the context admin user and how do i do that?'''<br><br />
A: for the context admin, all modules must be enabled the like the users in the context have<br />
<br />
'''Q: Can the Open-Xchange GUI be used to replace my existing Webmail system?'''<br><br />
A: Of course! the Open-Xchange GUI can be used to replace the existing Webmail system. <br />
<br />
'''Q: When i create new users, they have only mail and contacts enabled, why?'''<br><br />
A: The default module access is webmail, all others have to be enabled through te provisioning interface as described in the provisioning manual<br />
<br />
'''Q: What is the context admin user for?'''<br><br />
A: The context admin is a special user in the groupware who is able to log in to the GUI. This user gets shared items from deleted users on deletion.<br />
<br />
'''Q: How do i report bugs to Open-Xchange?'''<br><br />
A: Bugs are to be reported via the Open-Xchange ticket system. New tickets are created through an email to support@open-xchange.com. For those who have a support contract, the support registration code needs to be in the body of that email. <br />
<br />
'''Q: Why is the link in notification mails broken?'''<br><br />
A: The link is generated from the template in the configuration file /opt/open-xchange/etc/groupware/notification.properties<br />
<br />
'''Q: Why do i get an error when i click on Extras in the groupware GUI?'''<br><br />
A: Behind that extra link, there is a plugin which can also be a own developed one. The Default plugin, shipped with the software is to be configured in the file /opt/open-xchange/etc/groupware/configjump.properties<br />
<br />
'''Q: What kind of authentication plugins are available?'''<br><br />
A: The default plugin, shipped with the software, authenticates against the Open-Xchange <br />
database. Other examples are included in the development documentation.<br />
<br />
'''Q: Is there a limit for the number of users, groups and resources in a context?'''<BR><br />
A: basically there only is a theoretical limit of 2^31 for all together per context<br />
<br />
'''Q: Why do resources need to have a email address and for what is it used?'''<br><br />
A: A email address for a resource is required by outlook so that outlook is able to manage resources. The OX server does not sent emails to that address.<br />
<br />
<!--'''Q: is there a mobility solution available so that i can get access to data in the Open-Xchange server on my mobile?'''<br><br />
A: A Funambol client is available which is able to sync between the Open-Xchange server and the mobility client. The needed connector is available from [http://funambol.com/opensource/downloads.php Funambol]<br />
--!></div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=VCard_and_ICal_support&diff=22090VCard and ICal support2016-06-29T13:46:06Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div><div class="title">VCard and ICal support</div><br />
<br />
__TOC__<br />
<br />
'''Abstract''': VCard and ICal are definitions of text-based PIM information in files. In OX terms, VCard defines ''contact'' data, while ICal defines both ''Tasks'' and ''Appointments''. ICal internally identifies itself as VCalendar 2.0, which illustrates who closely related both protocols are. That is why questions on both formats are answered in one article.<br />
<br />
This article deals with features that are in VCard and ICal but are problematic within the OX. This also applies to CardDAV and CalDAV, because those services are also based on these two formats.<br />
<br />
== RRULE: "The second last sunday in a month" ==<br />
ICal allows you to define an appointment which occurs "the second last sunday every month". OX simply does not. We only support counting from the beginning of a month, but not from the end. Since a month might have either four or five occurrences of a certain day, it is not possible for us to simply convert this.<br />
<br />
Behavior: An ICal appointment containing this property is '''not imported'''.<br />
<br />
See [http://tools.ietf.org/html/rfc2445#section-4.8.5.4 RFC 2445, 4.8.5.4 Recurrence Rule]<br />
<br />
== ALARM: "Remind me four times" ==<br />
ICal allows you to set an alarm which should be repeated four times before ending. This might be interesting for an alarm clock, but for a web-based tool with will be used asynchronous in most cases, we handle this differently. Therefore, OX does not support an ALARM with a REPEAT property.<br />
<br />
Behavior: This property is '''ignored'''.<br />
<br />
Reference: [http://tools.ietf.org/html/rfc2445#section-4.8.6.2 RFC 2445, 4.8.6.2 Repeat count]<br />
<br />
== Limited amount of fields ==<br />
The basic problem: Open-Xchange only supports a fixed set of fields. VCards and ICals, on the other hand, allow for a theoretically unlimited amount of fields, sometimes by adding different types (thereby changing the semantic information, e.g. home and business addresses), sometimes by simply something (e.g. exceptions to an appointment series). This works in most cases (e.g. for appointment series) but not in others (see below).<br />
<br />
=== URL ===<br />
Open-Xchange only supports one URL per user. VCards allow several. URL is not supported.<br />
<br />
=== TEL ===<br />
As said, Open-Xchange only supports a fixed set of phone number fields, all of which have a semantic meaning (so they are not used to store other phone numbers even if space is needed). VCards, on the other hand, allow for a theoretically unlimited amount of phone numbers via different type combinations (or repeating the same one, too). <br />
<br />
In practice this is usually not much of a problem, for people do not have that many, but for all who are interested in the details: <br />
* The basic idea is that the first candidate for a field is stored there, and further ones are<br />
** either moved into the next available fallback field<br />
** or dropped in case there is no fallback field <br />
* The marker "pref" in VCards, denoting a preferred number, is taken into account during that process<br />
* If type is voice and fax (confusing), we consider it ''voice''<br />
* OX does not distinguish between ''work'' and ''home'' cellphones, pagers, idsn, car or text phones.<br />
* The types ''home'', ''work'' and ''dom'' are used to differentiate between the ''home'', ''business'' and ''other'' fax- and phone numbers<br />
* If no specific type is defined, the "business" fields are preferred against "home" and "other" fields.<br />
<br />
This is how we map VCard fields to [https://documentation.open-xchange.com/ HTTP_API (OX contact fields)]:<br />
{|<br />
! VCard type<br />
! OX column number<br />
! OX field name<br />
! Fallback OX fields<br />
! Fallback OX field names<br />
|-<br />
|-<br />
| pager<br />
| 560<br />
| telephone_pager<br />
| 553<br />
| telephone_other<br />
|-<br />
| textphone<br />
| 564<br />
| telephone_ttytdd<br />
| 553<br />
| telephone_other<br />
|-<br />
| car<br />
| 546<br />
| telephone_car<br />
| 553<br />
| telephone_other<br />
|-<br />
| isdn<br />
| 559<br />
| telephone_isdn<br />
| 553<br />
| telephone_other<br />
|-<br />
| cell<br />
| 551<br />
| cellular_telephone1<br />
| 552, 553<br />
| cellular_telephone2, telephone_other<br />
|-<br />
| voice,work<br />
| 542 <br />
| telephone_business1<br />
| 543, 547, 553<br />
| telephone_business2, telephone_company, telephone_other<br />
|-<br />
| voice,home<br />
| 548<br />
| telephone_home1<br />
| 589, 553<br />
| telephone_home2, telephone_other<br />
|-<br />
| voice,dom<br />
| 553<br />
| telephone_other<br />
|-<br />
| voice<br />
| 542 <br />
| telephone_business1<br />
| 543, 547, 548, 589, 553<br />
| telephone_business2, telephone_company, telephone_home1, telephone_home2, telephone_other<br />
|-<br />
| fax,work<br />
| 544<br />
| fax_business<br />
| 554<br />
| fax_other<br />
|-<br />
| fax,home<br />
| 550<br />
| fax_home<br />
| 554<br />
| fax_other<br />
|-<br />
| fax,dom<br />
| 554<br />
| fax_other<br />
|-<br />
| fax<br />
| 544<br />
| fax_business<br />
| 550, 554<br />
| fax_home, fax_other<br />
|}<br />
<br />
== Distribution lists ==<br />
Distribution lists are specific to OX. VCards do not really have a functional equivalent. So the export of distribution lists is not supported.<br />
<br />
== Other unsupported fields ==<br />
These are just the field names as given the the RFCs, since we are unable to guess what they will be called in the client app.<br />
<br />
=== Appointments ===<br />
ATTACH, COMMENT, CONTACT, CREATED, DTSTAMP, EXRULE, GEO, ORGANIZER, PRIORITY, RDATE, REQUEST-STATUS, STATUS<br />
<br />
=== Contacts ===<br />
GEO, KEY, LABEL, LOGO, MAILER, NAME, PRODID, PROFILE, REV, SORT-STRING, SOUND, SOURCE, TZ<br />
<br />
=== Tasks ===<br />
ATTACH, COMMENT, CONTACT, EXDATE, EXRULE, GEO, LOCATION, ORGANIZER, REQUEST-STATUS, RESOURCES, RDATE, URL<br />
<br />
<br />
<br />
[[Category: OX6]]<br />
[[Category: AppSuite]]<br />
<br />
[[Category: Backend]]<br />
<br />
[[Category: ICal]]<br />
[[Category: VCard]]<br />
[[Category: CalDAV]]<br />
[[Category: CardDAV]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Using_the_export_servlet&diff=22089Using the export servlet2016-06-29T13:43:42Z<p>Martin.schneider: Move to https://documentation.open-xchange.com/</p>
<hr />
<div>There are two things to do with the export servlet:<br />
<br />
* You can use it to export data from Open-Xchange Server<br />
** Example: Exporting you Contacts as vCards. <br />
* you can extend it to export new formats<br />
** Example: Currently, the CSV format can only be used to export contacts. You can extend it to export appointments. <br />
<br />
<br />
Exporting data using existing exporters is done using the API, as explained in [https://documentation.open-xchange.com/ HTTP API (export module)].<br />
<br />
Adding a new exporter is explained in [[Building an exporter]].<br />
<br />
See also: [[Using the import servlet]].<br />
<br />
<br />
<br />
[[Category:OX6]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Using_the_import_servlet&diff=22088Using the import servlet2016-06-29T13:42:36Z<p>Martin.schneider: </p>
<hr />
<div>== Basics ==<br />
There are two things to do with the import servlet:<br />
<br />
* You can use it to import data into Open-Xchange Server<br />
** Example: ''Importing your Outlook data by exporting it as CSV and then importing it''.<br />
* you can extend it to import new formats<br />
** Example: ''Currently, the CSV format can only be used to import contacts. You can extend it to import appointments''.<br />
<br />
Importing data using existing importers is done using the API, as explained in [https://documentation.open-xchange.com/ HTTP API (import module)].<br />
<br />
== Details ==<br />
A collection of details about the importer<br />
<br />
=== Date formats in CSV files===<br />
While the date formats of both iCal and vCard are pretty clear, csv can be defined freely (insert "of course" or "sadly" as you like).<br />
<br />
Microsoft Outlook does as it likes:<br />
* the German version uses DD.MM.YYYY<br />
* the English version uses MM-DD-YYYY<br />
<br />
Our own format uses the timestamp format. Advantage: You can use hours and minutes. Disadvantage: You'll have to use negative numbers for dates before 1-1-1970.<br />
<br />
Information for developers: The date format interpreters are build to be exchangeable, you can use your own format there.<br />
<br />
== Other ==<br />
Adding a new importer is explained in [[Building an importer]].<br />
<br />
See also: [[Using the export servlet]].<br />
<br />
<br />
<br />
[[Category:OX6]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode&diff=21972AppSuite:Sharing and Guest Mode2016-06-03T12:09:19Z<p>Martin.schneider: Added share limit paragraph</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 />
== Limit file accesses for named/anonymous guests (since 7.8.2) ==<br />
<br />
As links to shares might be shared without knowing the audience we introduced a mechanism to prevent abuse.<br />
<br />
Therefor the possibility to define size and/or count limits for named/anonymous guests has been introduced. As internal users can be considered as reliable it is not possible to define limits for them. <br />
<br />
For named and anonymous guests there are two kinds of limits which apply to a defined time frame. The time frame acts as a sliding time window which means that based on the current request all earlier requests matching the time frame are cumulated and evaluated if one of the two limits is exceeded. If so, the request will be answered with an exception.<br />
<br />
The two limits mentioned above are:<br />
<br />
* size limits: how many content (in bytes) should the guest be allowed to download (within the defined time frame).<br />
* count limits: how often should the guest be allowed to download a file or folder (within the defined time frame). <br />
<br />
Named and anonymos guests can have different limits. Limits are valid for downloads of files and folders. Preview of images is not considered within the limit.<br />
<br />
<br />
'''''Administrator Notes:'''''<br />
<br />
* The anti-abuse mechanism will be available after updating the package open-xchange-core to release 7.8.2<br />
* Additional parameters are located within the configuration file <code>share.properties</code><br />
* Per default the feature is disabled<br />
* To enable the feature you have to set <code>com.openexchange.share.servlet.limit.enabled</code> to <code>true</code>. If not enabled all additional checks will be skipped. If you would like to set limits via config cascade those will only be checked if the feature itself is enabled.<br />
* To be more flexible the administrator is able to overwrite limits by using the config cascade. As guests do not have fixed user identifiers only the 'context' level scope is supported.<br />
<br />
After the feature is enabled you have the ability to configure fine-grained accesses via: <br />
* <code>com.openexchange.share.servlet.limit.timeFrame.guests</code>: sliding time frame (in milliseconds) the limits are valid for named guests. Setting to 0 will disable the check for named guests (if not overwritten via config cascade).<br />
* <code>com.openexchange.share.servlet.limit.timeFrame.links</code>: sliding time frame (in milliseconds) the limits are valid for anonymous guests. Setting to 0 will disable the check for anonymous guests (if not overwritten via config cascade).<br />
* <code>com.openexchange.share.servlet.limit.size.guests</code>: the limit in bytes for named guests (valid for aboves time frame). Setting to 0 will disable the size check for named guests (if not overwritten via config cascade).<br />
* <code>com.openexchange.share.servlet.limit.size.links</code>: the limit in bytes for anonymous guests (valid for aboves time frame). Setting to 0 will disable the size check for anonymous guests (if not overwritten via config cascade).<br />
* <code>com.openexchange.share.servlet.limit.count.guests</code>: the limit for a number of downloads (valid for aboves time frame) for named guests. Setting to 0 will disable the count check for named guests (if not overwritten via config cascade).<br />
* <code>com.openexchange.share.servlet.limit.count.links</code>: the limit for a number of downloads (valid for aboves time frame) for anonymous guests. Setting to 0 will disable the count check for anonymous guests (if not overwritten via config cascade).<br />
<br />
=== Example configurations === <br />
<br />
A mixed configuration is possible. Have a look at the following examples assuming that <code>com.openexchange.share.servlet.limit.enabled</code> is set to <code>true</code>.<br />
<br />
The following configuration only checks the count limit for anonymous guests. Named guests and the limit for download sizes will not be checked<br />
* <code>com.openexchange.share.servlet.limit.timeFrame.guests:0</code> (# disabled)<br />
* <code>com.openexchange.share.servlet.limit.timeFrame.links:3600000</code> (# 60 minutes)<br />
* <code>com.openexchange.share.servlet.limit.size.guests:0</code> (# not considered as disabled)<br />
* <code>com.openexchange.share.servlet.limit.size.links:0</code> (# size for 60 minutes not checked)<br />
* <code>com.openexchange.share.servlet.limit.count.guests:0</code> (# not considered as disabled)<br />
* <code>com.openexchange.share.servlet.limit.count.links:100</code> (# 100 downloads within 60 minutes)<br />
<br />
The following configuration will check the count limit for named guests and the size limit for anonymous guests (both within the last 60 minutes).<br />
* <code>com.openexchange.share.servlet.limit.timeFrame.guests:3600000</code> (# 60 minutes)<br />
* <code>com.openexchange.share.servlet.limit.timeFrame.links:3600000</code> (# 60 minutes)<br />
* <code>com.openexchange.share.servlet.limit.size.guests:0</code> (# disabled)<br />
* <code>com.openexchange.share.servlet.limit.size.links:1073741824</code> (# 1 GB)<br />
* <code>com.openexchange.share.servlet.limit.count.guests:1000</code> (# 1000 downloads within 60 minutes)<br />
* <code>com.openexchange.share.servlet.limit.count.links:0</code> (# disabled)<br />
<br />
It is possible to reload an adapted configuration by using reloadconfiguration command line tool.<br />
<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:User_management&diff=20848AppSuite:User management2015-10-29T11:22:32Z<p>Martin.schneider: </p>
<hr />
<div><br />
== createuser ==<br />
<br />
'''<code>createuser</code>''' is the tool to create new users in a given context. The displayname must be unique in one context.<br />
<br />
<br />
=== Parameters ===<br />
<br />
{| border="1"<br />
|-<br />
| -h,--help<br />
|Prints a help text<br />
|-<br />
| --environment<br />
|Show infoabout commandline environment<br />
|-<br />
| --nonl<br />
|Remove all newlines (\n) from output<br />
|-<br />
| --responsetimeout &lt;integer&gt;<br />
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''<br />
|-<br />
| --extendedoptions <br />
|Set this if you want to see all options, use this instead of help option<br />
|-<br />
|csv-import &lt;CSV file&gt; <br />
| Full path to CSV file with user data to import. This option makes mandatory options obsolete, except credential options (if needed). <br />
|-<br />
| -c,--contextid &lt;integer&gt;<br />
|The id of the context<br />
|-<br />
| -u,--username &lt;string&gt;<br />
|Username of the user<br />
|-<br />
| -d,--displayname &lt;string&gt;<br />
|Display name of the user<br />
|-<br />
| -g,--givenname &lt;string&gt;<br />
|Given name for the user<br />
|-<br />
| -s,--surname &lt;string&gt;<br />
|Surname of the user<br />
|-<br />
| -p,--password &lt;string&gt;<br />
|Password for the user <br />
|-<br />
| -e,--email &lt;string&gt;<br />
|Primary mail address <br />
|-<br />
| -l,--language &lt;lang&gt;<br />
|Language for the user (de_DE,en_US,fr_FR)<br />
|-<br />
| -t,--timezone &lt;timezone&gt;<br />
|Timezone of the user (Europe/Berlin)<br />
|-<br />
| -x,--department &lt;string&gt;<br />
|Department of the user <br />
|-<br />
| -z,--company &lt;string&gt;<br />
|Company of the user <br />
|-<br />
| -a,--aliases &lt;string&gt;<br />
|E-Mail aliases of the user, separated by ","<br />
|-<br />
| --access-combination-name &lt;access-combination-name&gt;<br />
|Access combination name<br />
|-<br />
| --addguipreferences &lt;addguipreferences&gt;<br />
|Add a GUI setting (key=value)<br />
|}<br />
For the GUI preferences please also see [http://oxpedia.org/wiki/index.php?title=Gui_path]<br />
<br />
<br />
==== --csv-import <CSV file> ====<br />
<br />
Full path to CSV file with user data to<br />
import. This option makes mandatory command line options obsolete, except credential options (if needed). But they have to be set in the CSV file.<br />
<br />
<br />
With this option you can specify a csv file<br />
(a full pathname must be given) with the data which should be imported. The columnnames in the CSV file must be the same as the long-options of the command line tools, without the prefix<br />
"--".<br />
<br />
<br />
This option will normally be used to fill new large installations with the new data. So instead of calling the command line tools in a shell script every time, just a csv file needs to<br />
be created, containing the whole data.<br />
<br />
<br />
Note that the credentials of the masteradmin in the createcontext call must be given on the command line with the -A and -P options nevertheless - if<br />
authentication is enabled. If the createuser command line tool is used, the credentials are part of the csv file, and cannot be set as options on the command line itself. The reason for this<br />
different behavior is that different contexts have different credentials for the admin user, so they must be set in every line of the csv file. Opposed to this the credentials of the masteradmin<br />
are always the same.<br />
<br />
=== Extended options ===<br />
<br />
{| border="1"<br />
|-<br />
| --email1 &lt;string&gt;<br />
|Email1<br />
|-<br />
| --birthday &lt;datevalue&gt;<br />
|Birthday<br />
|-<br />
| --anniversary &lt;datevalue&gt;<br />
|Anniversary<br />
|-<br />
| --branches &lt;string&gt;<br />
|Branches<br />
|-<br />
| --business_category &lt;string&gt;<br />
|Business_category<br />
|-<br />
| --postal_code_business &lt;string&gt;<br />
|Postal_code_business<br />
|-<br />
| --state_business &lt;string&gt;<br />
|State_business<br />
|-<br />
| --street_business &lt;string&gt;<br />
|Street_business<br />
|-<br />
| --telephone_callback &lt;string&gt;<br />
|Telephone_callback<br />
|-<br />
| --city_home &lt;string&gt;<br />
|City_home<br />
|-<br />
| --commercial_register &lt;string&gt;<br />
|Commercial_register<br />
|-<br />
| --country_home &lt;string&gt;<br />
|Country_home<br />
|-<br />
| --email2 &lt;string&gt;<br />
|Email2<br />
|-<br />
| --email3 &lt;string&gt;<br />
|Email3<br />
|-<br />
| --employeetype &lt;string&gt;<br />
|EmployeeType<br />
|-<br />
| --fax_business &lt;string&gt;<br />
|Fax_business<br />
|-<br />
| --fax_home &lt;string&gt;<br />
|Fax_home<br />
|-<br />
| --fax_other &lt;string&gt;<br />
|Fax_other<br />
|-<br />
| --imapserver &lt;string&gt;<br />
|ImapServer<br />
|-<br />
| --imaplogin &lt;string&gt;<br />
|ImapLogin<br />
|-<br />
| --smtpserver &lt;string&gt;<br />
|SmtpServer<br />
|-<br />
| --instant_messenger1 &lt;string&gt;<br />
|Instant_messenger1<br />
|-<br />
| --instant_messenger2 &lt;string&gt;<br />
|Instant_messenger2<br />
|-<br />
| --telephone_ip &lt;string&gt;<br />
|Telephone_ip<br />
|-<br />
| --telephone_isdn &lt;string&gt;<br />
|Telephone_isdn<br />
|-<br />
| --mail_folder_drafts_name &lt;string&gt;<br />
|Mail_folder_drafts_name<br />
|-<br />
| --mail_folder_sent_name &lt;string&gt;<br />
|Mail_folder_sent_name<br />
|-<br />
| --mail_folder_spam_name &lt;string&gt;<br />
|Mail_folder_spam_name<br />
|-<br />
| --mail_folder_trash_name &lt;string&gt;<br />
|Mail_folder_trash_name<br />
|-<br />
| --mail_folder_archive_full_name &lt;string&gt;<br />
|Mail_folder_archive_full_name<br />
|-<br />
| --manager_name &lt;string&gt;<br />
|Manager_name<br />
|-<br />
| --marital_status &lt;string&gt;<br />
|Marital_status<br />
|-<br />
| --cellular_telephone1 &lt;string&gt;<br />
|Cellular_telephone1<br />
|-<br />
| --cellular_telephone2 &lt;string&gt;<br />
|Cellular_telephone2<br />
|-<br />
| --info &lt;string&gt;<br />
|Info<br />
|-<br />
| --nickname &lt;string&gt;<br />
|Nickname<br />
|-<br />
| --number_of_children &lt;string&gt;<br />
|Number_of_children<br />
|-<br />
| --note &lt;string&gt;<br />
|Note<br />
|-<br />
| --number_of_employee &lt;string&gt;<br />
|Number_of_employee<br />
|-<br />
| --telephone_pager &lt;string&gt;<br />
|Telephone_pager<br />
|-<br />
| --password_expired &lt;booleanvalue&gt;<br />
|Password_expired<br />
|-<br />
| --telephone_assistant &lt;string&gt;<br />
|Telephone_assistant<br />
|-<br />
| --telephone_business1 &lt;string&gt;<br />
|Telephone_business1<br />
|-<br />
| --telephone_business2 &lt;string&gt;<br />
|Telephone_business2<br />
|-<br />
| --telephone_car &lt;string&gt;<br />
|Telephone_car<br />
|-<br />
| --telephone_company &lt;string&gt;<br />
|Telephone_company<br />
|-<br />
| --telephone_home1 &lt;string&gt;<br />
|Telephone_home1<br />
|-<br />
| --telephone_home2 &lt;string&gt;<br />
|Telephone_home2<br />
|-<br />
| --telephone_other &lt;string&gt;<br />
|Telephone_other<br />
|-<br />
| --postal_code_home &lt;string&gt;<br />
|Postal_code_home<br />
|-<br />
| --profession &lt;string&gt;<br />
|Profession<br />
|-<br />
| --telephone_radio &lt;string&gt;<br />
|Telephone_radio<br />
|-<br />
| --room_number &lt;string&gt;<br />
|Room_number<br />
|-<br />
| --sales_volume &lt;string&gt;<br />
|Sales_volume<br />
|-<br />
| --city_other &lt;string&gt;<br />
|City_other<br />
|-<br />
| --country_other &lt;string&gt;<br />
|Country_other<br />
|-<br />
| --middle_name &lt;string&gt;<br />
|Middle_name<br />
|-<br />
| --postal_code_other &lt;string&gt;<br />
|Postal_code_other<br />
|-<br />
| --state_other &lt;string&gt;<br />
|State_other<br />
|-<br />
| --street_other &lt;string&gt;<br />
|Street_other<br />
|-<br />
| --spouse_name &lt;string&gt;<br />
|Spouse_name<br />
|-<br />
| --state_home &lt;string&gt;<br />
|State_home<br />
|-<br />
| --street_home &lt;string&gt;<br />
|Street_home<br />
|-<br />
| --suffix &lt;string&gt;<br />
|Suffix<br />
|-<br />
| --tax_id &lt;string&gt;<br />
|Tax_id<br />
|-<br />
| --telephone_telex &lt;string&gt;<br />
|Telephone_telex<br />
|-<br />
| --telephone_ttytdd &lt;string&gt;<br />
|Telephone_ttytdd<br />
|-<br />
| --uploadFileSizeLimitPerFile &lt;string&gt;<br />
|uploadFileSizeLimitPerFile<br />
|-<br />
| --uploadFileSizeLimit &lt;string&gt;<br />
|uploadFileSizeLimit<br />
|-<br />
| --url &lt;string&gt;<br />
|Url<br />
|-<br />
| --userfield01 &lt;string&gt;<br />
|Userfield01<br />
|-<br />
| --userfield02 &lt;string&gt;<br />
|Userfield02<br />
|-<br />
| --userfield03 &lt;string&gt;<br />
|Userfield03<br />
|-<br />
| --userfield04 &lt;string&gt;<br />
|Userfield04<br />
|-<br />
| --userfield05 &lt;string&gt;<br />
|Userfield05<br />
|-<br />
| --userfield06 &lt;string&gt;<br />
|Userfield06<br />
|-<br />
| --userfield07 &lt;string&gt;<br />
|Userfield07<br />
|-<br />
| --userfield08 &lt;string&gt;<br />
|Userfield08<br />
|-<br />
| --userfield09 &lt;string&gt;<br />
|Userfield09<br />
|-<br />
| --userfield10 &lt;string&gt;<br />
|Userfield10<br />
|-<br />
| --userfield11 &lt;string&gt;<br />
|Userfield11<br />
|-<br />
| --userfield12 &lt;string&gt;<br />
|Userfield12<br />
|-<br />
| --userfield13 &lt;string&gt;<br />
|Userfield13<br />
|-<br />
| --userfield14 &lt;string&gt;<br />
|Userfield14<br />
|-<br />
| --userfield15 &lt;string&gt;<br />
|Userfield15<br />
|-<br />
| --userfield16 &lt;string&gt;<br />
|Userfield16<br />
|-<br />
| --userfield17 &lt;string&gt;<br />
|Userfield17<br />
|-<br />
| --userfield18 &lt;string&gt;<br />
|Userfield18<br />
|-<br />
| --userfield19 &lt;string&gt;<br />
|Userfield19<br />
|-<br />
| --userfield20 &lt;string&gt;<br />
|Userfield20<br />
|-<br />
| --city_business &lt;string&gt;<br />
|City_business<br />
|-<br />
| --country_business &lt;string&gt;<br />
|Country_business<br />
|-<br />
| --assistant_name &lt;string&gt;<br />
|Assistant_name<br />
|-<br />
| --telephone_primary &lt;string&gt;<br />
|Telephone_primary<br />
|-<br />
| --categories &lt;string&gt;<br />
|Categories<br />
|-<br />
| --mail_folder_confirmed_ham_name &lt;string&gt;<br />
|Mail_folder_confirmed_ham_name<br />
|-<br />
| --mail_folder_confirmed_spam_name &lt;string&gt;<br />
|Mail_folder_confirmed_spam_name<br />
|-<br />
| --gui_spam_filter_capabilities_enabled &lt;booleanvalue&gt;<br />
|GUI_spam_filter_capabilities_enabled<br />
|-<br />
| --mailenabled &lt;true/false&gt;<br />
|Mailenabled<br />
|-<br />
| --defaultsenderaddress &lt;stringvalue&gt;<br />
|DefaultSenderAddress<br />
|-<br />
| --title &lt;string&gt;<br />
|Title<br />
|-<br />
| --position &lt;string&gt;<br />
|Position<br />
|-<br />
| --access-calendar &lt;on/off&gt;<br />
|Calendar module (Default is off)<br />
|-<br />
| --access-contacts &lt;on/off&gt;<br />
|Contact module access (Default is on)<br />
|-<br />
| --access-delegate-tasks &lt;on/off&gt;<br />
|Delegate tasks access (Default is off)<br />
|-<br />
| --access-edit-public-folder &lt;on/off&gt;<br />
|Edit public folder access (Default is off)<br />
|-<br />
| --access-ical &lt;on/off&gt;<br />
|Ical module access (Default is off)<br />
|-<br />
| --access-infostore &lt;on/off&gt;<br />
|Infostore module access (Default is off)<br />
|-<br />
| --access-read-create-shared-Folders &lt;on/off&gt;<br />
|Read create shared folder access (Default is off)<br />
|-<br />
| --access-syncml &lt;on/off&gt;<br />
|Syncml access (Default is off)<br />
|-<br />
| --access-active-sync &lt;on/off&gt;<br />
|Exchange Active Sync access (Default is off)<br />
|-<br />
| --access-usm &lt;on/off&gt;<br />
|Universal Sync Module access (Default is off)<br />
|-<br />
| --access-tasks &lt;on/off&gt;<br />
|Tasks access (Default is off)<br />
|-<br />
| --access-vcard &lt;on/off&gt;<br />
|Vcard access (Default is off)<br />
|-<br />
| --access-webdav &lt;on/off&gt;<br />
|Webdav access (Default is off)<br />
|-<br />
| --access-webdav-xml &lt;on/off&gt;<br />
|Webdav-Xml access (Default is off)<br />
|-<br />
|<br />
--access-webmail &lt;on/off&gt;<br />
|Webmail access (Default is on)<br />
|-<br />
| --access-publication &lt;on/off&gt;<br />
|Publication permission (Default is on). Note: access-publication needs access-infostore and is optional for Groupware+ and premium<br />
|-<br />
| --access-subscription &lt;on/off&gt;<br />
|Subscription permission (Default is on)<br />
|-<br />
| --access-edit-group &lt;on/off&gt;<br />
|Edit group access (Default is off)<br />
|-<br />
| --access-edit-resource &lt;on/off&gt;<br />
|Edit resource access (Default is off)<br />
|-<br />
| --access-edit-password &lt;on/off&gt;<br />
|Edit password access (Default is off)<br />
|-<br />
| --access-collect-email-addresses &lt;on/off&gt;<br />
|Edit collect email addresses (Default is off)<br />
|-<br />
| --access-multiple-mail-accounts &lt;on/off&gt;<br />
|Use multiple mail account feature (Default is off)<br />
|-<br />
| --access-global-address-book-disabled &lt;on/off&gt;<br />
|Access to global address book (Default is off). Note: Setting this option to true is only allowed in combination with PIM and Webmail rights. Note: There is a 'restoregaddefaults' script to restore the default permissions of the global address book folder. <br />
|-<br />
| --access--voipnow &lt;on/off&gt;<br />
|Access to VoiceOverIP feature.<br />
|-<br />
| --access-public-folder-editable &lt;on/off&gt;<br />
|Access to public folders. Allows or denies to see public folders. <br />
|-<br />
| --foldertree &lt;0/1&gt;<br />
|0 sets the OX standard folder tree and 1 sets the Outlook-like folder tree.<br />
|-<br />
| --access-olox20 &lt;on/off&gt;<br />
| Access to Olox2.0<br />
|}<br />
<br />
=== Open-Xchange module access ===<br />
<br />
With Open-Xchange it is<br />
possible to limit the access to the available modules per context i. e., all users in one context per default get the same access rights. The rights though can be changed per user. Currently,<br />
following modules are implemented: access-calendar, access-contacts, access-delegate-tasks, access-edit-public-folder, access-ical, access-infostore, access-read-create-shared-Folders,<br />
access-tasks, access-vcard, access-webdav, access-webdav-xml, access-syncml and access-webmail. There are several combinations possible and four are supported (not mentioned modules need to be<br />
disabled). This limitation is needed because some modules depend on access to others. There are different Open-Xchange packages available for the customer: Webmail+, PIM+, Groupware+, Premium.<br />
These packages have to be configured per context i. e., all users in a context need to use the same package. Each package consists of a combination of modules that has to be set up appropriately.<br />
The following sections quickly introduce the packages and their module configuration. Open-Xchange also provides the possibility to use "access combination names" when creating and changing<br />
contexts/users. If you want to change the package acess rights for a context, you can simply add the "access-combination-name" switch to the appropriate tool<br />
(createcontext,createuser,changecontext etc.).<br />
<br />
<br />
==== Webmail+ ====<br />
<br />
If there are no access rights specified when creating a new user Webmail+ is used as default. Webmail+ is a base package that allows access to the<br />
webmail interface and a personal address book. To grant access to this package, the following modules have to be set to "on" for all users in a context:<br />
<br />
<br />
{| border="1"<br />
|-<br />
|access-contacts<br />
|Access combination name: webmail_plus<br />
|-<br />
|access-webmail<br />
|Access combinationname: webmail_plus<br />
|}<br />
<br />
==== PIM+ ====<br />
<br />
PIM+<br />
is another base package that gives access to the webmailer, personal address book, calendar and tasks. Group appointments and delegating tasks are not supported. To grant access to this package,<br />
the following modules have to be set to "on" for all users in a context:<br />
<br />
<br />
{| border="1"<br />
|-<br />
|access-contacts<br />
|Access combination name: pim_plus<br />
|-<br />
|access-webmail<br />
|Access combination name: pim_plus<br />
|-<br />
|access-calendar<br />
|Access combination name: pim_plus<br />
|-<br />
|access-delegate-tasks<br />
|Access combination name: pim_plus<br />
|-<br />
|access-tasks<br />
|Access combination name: pim_plus<br />
|}<br />
<br />
==== Groupware+ ====<br />
<br />
Groupware+ is an upsell package that provides full groupware functionality: private, shared and public folders, conflict handling for appointments, team view. Furthermore, the InfoStore is<br />
available. To grant access to this package, the following modules have to be set to "on" for all users in a context:<br />
<br />
<br />
{| border="1"<br />
|-<br />
|access-contacts<br />
|Access combination name: groupware_plus<br />
|-<br />
|access-webmail<br />
|Access combination name: groupware_plus<br />
|-<br />
|access-calendar<br />
|Access combination name: groupware_plus<br />
|-<br />
|access-delegate-tasks<br />
|Access combination name: groupware_plus<br />
|-<br />
|access-tasks<br />
|Access combination name: groupware_plus<br />
|-<br />
|access-edit-public-folder<br />
|Access combination name: groupware_plus<br />
|-<br />
|access-infostore<br />
|Access combination name: groupware_plus<br />
|-<br />
|access-read-create-shared-Folders<br />
|Access combination name: groupware_plus<br />
|}<br />
<br />
==== Premium ====<br />
<br />
Premium is a desktop integration package. It provides the functionality of the "Groupware+" package and comes with interfaces to integrate with other software: The OXtender for MS Outlook and the<br />
WebDAV interface to integrate the InfoStore with desktops. To grant access to this package, the following modules have to be set to "on" for all users in a context:<br />
<br />
<br />
{| border="1"<br />
|-<br />
|access-contacts<br />
|Access combination name: premium<br />
|-<br />
|access-webmail<br />
|Access combination name: premium<br />
|-<br />
|access-calendar<br />
|Access combination name: premium<br />
|-<br />
|access-delegate-tasks<br />
|Access combination name: premium<br />
|-<br />
|access-tasks<br />
|Access combination name: premium<br />
|-<br />
|access-edit-public-folder<br />
|Access combination name: premium<br />
|-<br />
|access-infostore<br />
|Access combination name: premium<br />
|-<br />
|access-read-create-shared-Folders<br />
|Access combination name: premium<br />
|-<br />
|access-ical<br />
|Access combination name: premium<br />
|-<br />
|access-vcard<br />
|Access combination name: premium<br />
|-<br />
|access-webdav<br />
|Access combination name: premium<br />
|-<br />
|access-webdavxml<br />
|Access combination name: premium<br />
|}<br />
<br />
==== All ====<br />
The setting <code>all</code> is equivalent to <code>premium</code> for ordinary users. For context administrators, it adds the right <code>publicfoldereditable</code>, which allows the admin to change the access rights to public folders for groups.<br />
<br />
==== Package access configuration ====<br />
<br />
This section provides a quick overview about the different packages that can be configured per context and the<br />
required access configuration:<br />
<br />
<br />
{| border="1"<br />
|-<br />
|Module<br />
|Webmail+<br />
|PIM+<br />
|Groupware+<br />
|Premium<br />
|-<br />
| -access-calendar<br />
|off<br />
|on<br />
|on<br />
|on<br />
|-<br />
| -access-contacts<br />
|on<br />
|on<br />
|on<br />
|on<br />
|-<br />
| -access-delegate-tasks<br />
|off<br />
|on<br />
|on<br />
|on<br />
|-<br />
| -access-edit-public-folder<br />
|off<br />
|off<br />
|on<br />
|on<br />
|-<br />
| -access-ical<br />
|off<br />
|off<br />
|off<br />
|on<br />
|-<br />
| -access-infostore<br />
|off<br />
|off<br />
|on<br />
|on<br />
|-<br />
| -access-read-create-shared-Folders<br />
|off<br />
|off<br />
|on<br />
|on<br />
|-<br />
| -access-syncml<br />
|off<br />
|off<br />
|off<br />
|off<br />
|-<br />
|–access-tasks<br />
|off<br />
|on<br />
|on<br />
|on<br />
|-<br />
| -access-vcard<br />
|off<br />
|off<br />
|off<br />
|on<br />
|-<br />
| -access-webdav<br />
|off<br />
|off<br />
|off<br />
|on<br />
|-<br />
| -access-webdav-xml<br />
|off<br />
|off<br />
|off<br />
|on<br />
|-<br />
| -access-webmail<br />
|on<br />
|on<br />
|on<br />
|on<br />
|}<br />
<br />
=== Extra parameters when authentication is enabled ===<br />
<br />
{| border="1"<br />
|-<br />
| -A,--adminuser &lt;string&gt;<br />
|Context admin user name<br />
|-<br />
| -P,--adminpass &lt;string&gt;<br />
|Context admin password<br />
|}<br />
<br />
=== Return value ===<br />
<br />
<code>0</code> on success<br />
<br />
<code>&gt;0</code> on failure<br />
<br />
<br />
=== Mandatory parameters ===<br />
<br />
<code>contextid {adminuser adminpass} username displayname givenname surname password email</code><br />
<br />
=== Command output ===<br />
<br />
On success:<br />
<br />
<code>user &lt;userid&gt; in context &lt;contextid&gt; created</code><br />
<br />
On failure:<br />
<br />
<code>user in context &lt;contextid&gt; could not be created: &lt;reason from server&gt;</code><br />
<br />
<br />
=== Example ===<br />
<br />
<code>root@oxhe~# </code>'''<code>/opt/open-xchange/sbin/createuser -c 123 -u jd -d "john doe"<br />
-g John -s Doe -p userpw -e jd@example.com</code>'''<br />
<br />
<br />
<code>user 3 in context 123 created</code><br />
<br />
<br />
== deleteuser ==<br />
<br />
'''<code>deleteuser</code>''' is the tool to delete a user in a given context. If you delete a user the public folder entries of this user are<br />
transferred to the admin user. All other data are deleted.<br />
<br />
<br />
=== Parameters ===<br />
<br />
{| border="1"<br />
|-<br />
| -h,--help<br />
|Prints a help text<br />
|-<br />
| --environment<br />
|Show info about commandline environment<br />
|-<br />
| --nonl<br />
|Remove all newlines (\n) from output<br />
|-<br />
| --responsetimeout &lt;integer&gt;<br />
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''<br />
|-<br />
| -c,--contextid &lt;integer&gt;<br />
|The id of them context<br />
|-<br />
| -i,--userid &lt;integer&gt;<br />
|Id of the user<br />
|-<br />
| -u,--username &lt;string&gt;<br />
|Username ofthe user<br />
|}<br />
<br />
=== Extra parameters when authentication is enabled ===<br />
<br />
{| border="1"<br />
|-<br />
| -A,--adminuser &lt;string&gt;<br />
|Context Admin user name<br />
|-<br />
| -P,--adminpass &lt;string&gt;<br />
|Context Admin password<br />
|}<br />
<br />
=== Return value ===<br />
<br />
<code>0</code> on success<br />
<br />
<code>&gt;0</code> on failure<br />
<br />
<br />
=== Mandatory parameters ===<br />
<code>contextid {adminuser adminpass} (userid or username)</code><br />
<br />
=== Command output ===<br />
<br />
On success:<br />
<br />
<code>user &lt;userid&gt; in context &lt;contextid&gt; deleted</code><br />
<br />
<br />
On failure:<br />
<br />
<code>user &lt;userid&gt; in context &lt;contextid&gt; could not be deleted: &lt;reason from<br />
server&gt;</code><br />
<br />
<br />
=== Example ===<br />
<br />
<code>root@oxhe~# </code>'''<code> /opt/open-xchange/deleteuser -c 123 -i 3</code>'''<br />
<br />
<code>user 3 in context 123 deleted</code><br />
<br />
<br />
== listuser ==<br />
<br />
'''<code>listuser</code>''' is the tool to list and search for users.<br />
<br />
<br />
=== Parameters ===<br />
<br />
{| border="1"<br />
|-<br />
| -h,--help<br />
|Prints a help text<br />
|-<br />
| --environment<br />
|Show info about commandline environment<br />
|-<br />
| --nonl<br />
|Remove all newlines (\n) from output<br />
|-<br />
| --responsetimeout &lt;integer&gt;<br />
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''<br />
|-<br />
| -c,--contextid &lt;integer&gt;<br />
|The id of the context<br />
|-<br />
| -s,--searchpattern &lt;string&gt;<br />
|Search/List pattern, default “*”<br />
|-<br />
| --csv<br />
|Command output as csv<br />
|-<br />
| -i,--ignorecase <br />
|Do a case-insensitive search with the given search pattern<br />
|-<br />
| --includeguests<br />
|Add guest users to listing '''Available with v7.8.0'''<br />
|-<br />
| --excludeusers<br />
|Exclude usual users from listing '''Available with v7.8.0'''<br />
|}<br />
<br />
=== Extra parameters when authentication is enabled ===<br />
<br />
{| border="1"<br />
|-<br />
| -A,--adminuser &lt;string&gt;<br />
|Context Admin user name<br />
|-<br />
| -P,--adminpass &lt;string&gt;<br />
|Context Admin password<br />
|}<br />
<br />
=== Return value ===<br />
<br />
<code>0</code> on success<br />
<br />
<code>&gt;0</code> on failure<br />
<br />
=== Mandatory parameters ===<br />
<code>contextid adminuser adminpass</code><br />
<br />
=== Command output ===<br />
<br />
Standard output (only a subset of available attributes are printed also only disabled<br />
modules):<br />
<br />
<br />
{| border="1"<br />
|-<br />
|id<br />
|enabled<br />
|imapServer<br />
|smtpserver<br />
|language<br />
|Webdav<br />
|WebdavXml<br />
|-<br />
|3<br />
|true<br />
|localhost<br />
|localhost<br />
|en_US<br />
|false<br />
|false<br />
|}<br />
<br />
csv output: <br />
Name,Language,Id,Display_name,PrimaryEmail,MaxQuota,UsedQuota,Email1,Mailenabled,Password,Sur_name,Given_name,<br />
FilestoreId,FilestoreOwner,Filestore_name,Birthday,Anniversary,Branches,Business_category,Postal_code_business,<br />
State_business,Street_business,Telephone_callback,City_home,Commercial_register,Country_home,Company,Department,<br />
Email2,Email3,EmployeeType,Fax_business,Fax_home,Fax_other,ImapServer,ImapLogin,SmtpServer,Instant_messenger1,<br />
Instant_messenger2,Telephone_ip,Telephone_isdn,Mail_folder_drafts_name,Mail_folder_sent_name,<br />
Mail_folder_spam_name,Mail_folder_trash_name,Mail_folder_archive_full_name,Manager_name,Marital_status,Cellular_telephone1,Cellular_telephone2,<br />
Info,Nickname,Number_of_children,Note,Number_of_employee,Telephone_pager,Password_expired,Telephone_assistant,<br />
Telephone_business1,Telephone_business2,Telephone_car,Telephone_company,Telephone_home1,Telephone_home2,<br />
Telephone_other,Position,Postal_code_home,Profession,Telephone_radio,Room_number,Sales_volume,City_other,<br />
Country_other,Middle_name,Postal_code_other,State_other,Street_other,Spouse_name,State_home,Street_home,Suffix,<br />
Tax_id,Telephone_telex,Timezone,Title,Telephone_ttytdd,UploadFileSizeLimit,UploadFileSizeLimitPerFile,Url,<br />
Userfield01,Userfield02,Userfield03,Userfield04,Userfield05,Userfield06,Userfield07,Userfield08,Userfield09,<br />
Userfield10,Userfield11,Userfield12,Userfield13,Userfield14,Userfield15,Userfield16,Userfield17,Userfield18,<br />
Userfield19,Userfield20,Aliases,City_business,Country_business,Assistant_name,Telephone_primary,Categories,<br />
PasswordMech,Mail_folder_confirmed_ham_name,Mail_folder_confirmed_spam_name,GUI_Spam_filter_capabilities_enabled,<br />
DefaultSenderAddress,FolderTree,UserAttributes,GuiPreferences,access-calendar,access-contacts,<br />
access-delegate-tasks,access-edit-public-folder,access-ical,access-infostore,<br />
access-read-create-shared-Folders,access-syncml,access-tasks,access-vcard,access-webdav,access-webdav-xml,<br />
access-webmail,access-edit-group,access-edit-resource,access-edit-password,access-collect-email-addresses,<br />
access-multiple-mail-accounts,access-subscription,access-publication,access-active-sync,access-usm,<br />
access-olox20,access-denied-portal,access-global-address-book-disabled,access-public-folder-editable<br />
<br />
=== Example ===<br />
<br />
<pre> root@oxhe:~# /opt/open-xchange/sbin/listuser -c 6 Id Name Displayname Email 2 admin admin admin@example.com 3 holger Holger<br />
holger@example.com <br />
</pre><br />
<br />
<br />
== getusercapabilities ==<br />
<br />
'''<code>getusercapabilities</code>''' is the tool to list available capabilities for a certain user.<br />
<br />
<br />
=== Parameters ===<br />
<br />
{| border="1"<br />
|-<br />
| -h,--help<br />
|Prints a help text<br />
|-<br />
| --environment<br />
|Show info about commandline environment<br />
|-<br />
| --nonl<br />
|Remove all newlines (\n) from output<br />
|-<br />
| --responsetimeout &lt;integer&gt;<br />
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''<br />
|-<br />
| -c,--contextid &lt;integer&gt;<br />
|The id of the context<br />
|-<br />
| -i,--userid &lt;userid&gt;<br />
|Id of the user<br />
|-<br />
| -u,--username &lt;username&gt;<br />
|Username of the user<br />
|}<br />
<br />
=== Extra parameters when authentication is enabled ===<br />
<br />
{| border="1"<br />
|-<br />
| -A,--adminuser &lt;string&gt;<br />
|Context Admin user name<br />
|-<br />
| -P,--adminpass &lt;string&gt;<br />
|Context Admin password<br />
|}<br />
<br />
=== Return value ===<br />
<br />
<code>0</code> on success<br />
<br />
<code>&gt;0</code> on failure<br />
<br />
=== Mandatory parameters ===<br />
<code>contextid userid adminuser adminpass</code><br />
<br />
=== Command output ===<br />
<br />
Either "There are no capabilities set for user &lt;user-id&gt; in context &lt;context-id&gt;"<br />
or a line-wise listing of identifiers for available capabilities<br />
<br />
=== Example ===<br />
<br />
<pre> root@oxhe:~# /opt/open-xchange/sbin/getusercapabilities -c 6 -i 345<br />
</pre><br />
<br />
== changeuser ==<br />
<br />
The '''<code>changeuser</code>''' tool allows to modify attributes of an existing user in a given context. The displayname must be unique in<br />
one context.<br />
<br />
<br />
=== Parameters ===<br />
<br />
{| border="1"<br />
|-<br />
| -h,--help<br />
|Prints a help text<br />
|-<br />
| --environment<br />
|Show info about commandline environment<br />
|-<br />
| --nonl<br />
|Remove all newlines (\n) from output<br />
|-<br />
| --responsetimeout &lt;integer&gt;<br />
|response timeout in seconds for reading response from the backend (default 0s; infinite) '''Available with v7.8.0'''<br />
|-<br />
| --extendedoptions <br />
|Set this if you want to see all options, use this instead of help option<br />
|-<br />
| -c,--contextid &lt;integer&gt;<br />
|The id of the context<br />
|-<br />
| -i,--userid &lt;integer&gt;<br />
|Id of the user<br />
|-<br />
| -u,--username &lt;string&gt;<br />
|Username of the user <br />
|-<br />
| -d,--displayname &lt;string&gt;<br />
|Display name of the user <br />
|-<br />
| -g,--givenname &lt;string&gt;<br />
|Given name for the user <br />
|-<br />
| -s,--surname &lt;string&gt;<br />
|Surname of the user<br />
|-<br />
| -p,--password &lt;string&gt;<br />
|Password for the user <br />
|-<br />
| -e,--email &lt;string&gt;<br />
|Primary mail address <br />
|-<br />
| -l,--language &lt;lang&gt;<br />
|Language for the user (de_DE,en_US, fr_FR)<br />
|-<br />
| -t,--timezone &lt;timezone&gt;<br />
|Timezone of the user (Europe/Berlin)<br />
|-<br />
| -x,--department &lt;string&gt;<br />
|Department of the user<br />
|-<br />
| -z,--company &lt;string&gt;<br />
|Company of the user <br />
|-<br />
| -a,--aliases &lt;string&gt;<br />
|E-Mail aliases of the user, separated by ","<br />
|-<br />
| --access-combination-name &lt;access-combination-name&gt;<br />
|Access combination name <br />
|-<br />
| --addguipreferences &lt;addguipreferences&gt;<br />
|Add a GUI setting (key=value)<br />
|-<br />
| --removeguipreferences &lt;removeguipreferences&gt;<br />
|Remove a GUI setting <br />
|-<br />
| --access-denied-portal &lt;on/off&gt;<br />
|Denies portal access (Default is off)<br />
|-<br />
| --capabilities-to-add &lt;capabilities-to-add&gt;<br />
| The capabilities to add as a comma-separated string (from 7.2.0 on)<br />
|-<br />
| --capabilities-to-remove &lt;capabilities-to-remove&gt;<br />
|The capabilities to remove as a comma-separated string (from 7.2.0 on)<br />
|-<br />
| --capabilities-to-drop &lt;capabilities-to-drop&gt;<br />
|The capabilities to drop; e.g. cleanse from storage; as a comma-separated string (from 7.6.0 on)<br />
|}<br />
For the GUI preferences please also see http://www.open-xchange.com/wiki/index.php?title=Gui_path<br />
<br />
=== Extended options ===<br />
<br />
{| border="1"<br />
|-<br />
| --email1 &lt;string&gt;<br />
|Email1<br />
|-<br />
| --mailenabled &lt;booleanvalue &gt;<br />
|Mailenabled<br />
|-<br />
| --birthday &lt;datevalue&gt;<br />
|Birthday<br />
|-<br />
| --anniversary &lt;datevalue&gt;<br />
|Anniversary<br />
|-<br />
| --branches &lt;string&gt;<br />
|Branches<br />
|-<br />
| --business_category &lt;string&gt;<br />
|Business_category<br />
|-<br />
| --postal_code_business &lt;string&gt;<br />
|Postal_code_business<br />
|-<br />
| --state_business &lt;string&gt;<br />
|State_business<br />
|-<br />
| --street_business &lt;string&gt;<br />
|Street_business<br />
|-<br />
| --telephone_callback &lt;string&gt;<br />
|Telephone_callback<br />
|-<br />
| --city_home &lt;string&gt;<br />
|City_home<br />
|-<br />
| --commercial_register &lt;string&gt;<br />
|Commercial_register<br />
|-<br />
| --country_home &lt;string&gt;<br />
|Country_home<br />
|-<br />
| --email2 &lt;string&gt;<br />
|Email2<br />
|-<br />
| --email3 &lt;string&gt;<br />
|Email3<br />
|-<br />
| --employeetype &lt;string&gt;<br />
|EmployeeType<br />
|-<br />
| --fax_business &lt;string&gt;<br />
|Fax_business<br />
|-<br />
| --fax_home &lt;string&gt;<br />
|Fax_home<br />
|-<br />
| --fax_other &lt;string&gt;<br />
|Fax_other<br />
|-<br />
| --imapserver &lt;string&gt;<br />
|ImapServer<br />
|-<br />
| --imaplogin &lt;string&gt;<br />
|ImapLogin<br />
|-<br />
| --smtpserver &lt;string&gt;<br />
|SmtpServer<br />
|-<br />
| --instant_messenger1 &lt;string&gt;<br />
|Instant_messenger1<br />
|-<br />
| --instant_messenger2 &lt;string&gt;<br />
|Instant_messenger2<br />
|-<br />
| --telephone_ip &lt;string&gt;<br />
|Telephone_ip<br />
|-<br />
| --telephone_isdn &lt;string&gt;<br />
|Telephone_isdn<br />
|-<br />
| --mail_folder_drafts_name &lt;string&gt;<br />
|Mail_folder_drafts_name<br />
|-<br />
| --mail_folder_sent_name &lt;string&gt;<br />
|Mail_folder_sent_name<br />
|-<br />
| --mail_folder_spam_name &lt;string&gt;<br />
|Mail_folder_spam_name<br />
|-<br />
| --mail_folder_trash_name &lt;string&gt;<br />
|Mail_folder_trash_name<br />
|-<br />
| --mail_folder_archive_full_name &lt;string&gt;<br />
|Mail_folder_archive_full_name<br />
|-<br />
| --manager_name &lt;string&gt;<br />
|Manager_name<br />
|-<br />
| --marital_status &lt;string&gt;<br />
|Marital_status<br />
|-<br />
| --cellular_telephone1 &lt;string&gt;<br />
|Cellular_telephone1<br />
|-<br />
| --cellular_telephone2 &lt;string&gt;<br />
|Cellular_telephone2<br />
|-<br />
| --info &lt;string&gt;<br />
|Info<br />
|-<br />
| --nickname &lt;string&gt;<br />
|Nickname<br />
|-<br />
| --number_of_children &lt;string&gt;<br />
|Number_of_children<br />
|-<br />
| --note &lt;string&gt;<br />
|Note<br />
|-<br />
| --number_of_employee &lt;string&gt;<br />
|Number_of_employee<br />
|-<br />
| --telephone_pager &lt;string&gt;<br />
|Telephone_pager<br />
|-<br />
| --password_expired &lt;booleanvalue&gt;<br />
|Password_expired<br />
|-<br />
| --telephone_assistant &lt;string&gt;<br />
|Telephone_assistant<br />
|-<br />
| --telephone_business1 &lt;string&gt;<br />
|Telephone_business1<br />
|-<br />
| --telephone_business2 &lt;string&gt;<br />
|Telephone_business2<br />
|-<br />
| --telephone_car &lt;string&gt;<br />
|Telephone_car<br />
|-<br />
| --telephone_company &lt;string&gt;<br />
|Telephone_company<br />
|-<br />
| --telephone_home1 &lt;string&gt;<br />
|Telephone_home1<br />
|-<br />
| --telephone_home2 &lt;string&gt;<br />
|Telephone_home2<br />
|-<br />
| --telephone_other &lt;string&gt;<br />
|Telephone_other<br />
|-<br />
| --postal_code_home &lt;string&gt;<br />
|Postal_code_home<br />
|-<br />
| --profession &lt;string&gt;<br />
|Profession<br />
|-<br />
| --telephone_radio &lt;string&gt;<br />
|Telephone_radio<br />
|-<br />
| --room_number &lt;string&gt;<br />
|Room_number<br />
|-<br />
| --sales_volume &lt;string&gt;<br />
|Sales_volume<br />
|-<br />
| --city_other &lt;string&gt;<br />
|City_other<br />
|-<br />
| --country_other &lt;string&gt;<br />
|Country_other<br />
|-<br />
| --middle_name &lt;string&gt;<br />
|Middle_name<br />
|-<br />
| --postal_code_other &lt;string&gt;<br />
|Postal_code_other<br />
|-<br />
| --state_other &lt;string&gt;<br />
|State_other<br />
|-<br />
| --street_other &lt;string&gt;<br />
|Street_other<br />
|-<br />
| --spouse_name &lt;string&gt;<br />
|Spouse_name<br />
|-<br />
| --state_home &lt;string&gt;<br />
|State_home<br />
|-<br />
| --street_home &lt;string&gt;<br />
|Street_home<br />
|-<br />
| --suffix &lt;string&gt;<br />
|Suffix<br />
|-<br />
| --tax_id &lt;string&gt;<br />
|Tax_id<br />
|-<br />
| --telephone_telex &lt;string&gt;<br />
|Telephone_telex<br />
|-<br />
| --telephone_ttytdd &lt;string&gt;<br />
|Telephone_ttytdd<br />
|-<br />
| --url &lt;string&gt;<br />
|Url<br />
|-<br />
| --userfield01 &lt;string&gt;<br />
|Userfield01<br />
|-<br />
| --userfield02 &lt;string&gt;<br />
|Userfield02<br />
|-<br />
| --userfield03 &lt;string&gt;<br />
|Userfield03<br />
|-<br />
| --userfield04 &lt;string&gt;<br />
|Userfield04<br />
|-<br />
| --userfield05 &lt;string&gt;<br />
|Userfield05<br />
|-<br />
| --userfield06 &lt;string&gt;<br />
|Userfield06<br />
|-<br />
| --userfield07 &lt;string&gt;<br />
|Userfield07<br />
|-<br />
| --userfield08 &lt;string&gt;<br />
|Userfield08<br />
|-<br />
| --userfield09 &lt;string&gt;<br />
|Userfield09<br />
|-<br />
| --userfield10 &lt;string&gt;<br />
|Userfield10<br />
|-<br />
| --userfield11 &lt;string&gt;<br />
|Userfield11<br />
|-<br />
| --userfield12 &lt;string&gt;<br />
|Userfield12<br />
|-<br />
| --userfield13 &lt;string&gt;<br />
|Userfield13<br />
|-<br />
| --userfield14 &lt;string&gt;<br />
|Userfield14<br />
|-<br />
| --userfield15 &lt;string&gt;<br />
|Userfield15<br />
|-<br />
| --userfield16 &lt;string&gt;<br />
|Userfield16<br />
|-<br />
| --userfield17 &lt;string&gt;<br />
|Userfield17<br />
|-<br />
| --userfield18 &lt;string&gt;<br />
|Userfield18<br />
|-<br />
| --userfield19 &lt;string&gt;<br />
|Userfield19<br />
|-<br />
| --userfield20 &lt;string&gt;<br />
|Userfield20<br />
|-<br />
| --city_business &lt;string&gt;<br />
|City_business<br />
|-<br />
| --country_business &lt;string&gt;<br />
|Country_business<br />
|-<br />
| --assistant_name &lt;string&gt;<br />
|Assistant_name<br />
|-<br />
| --telephone_primary &lt;string&gt;<br />
|Telephone_primary<br />
|-<br />
| --categories &lt;string&gt;<br />
|Categories<br />
|-<br />
| --mail_folder_confirmed_ham_name &lt;string&gt;<br />
|Mail_folder_confirmed_ham_name<br />
|-<br />
| --mail_folder_confirmed_spam_name &lt;string&gt;<br />
|Mail_folder_confirmed_spam_name<br />
|-<br />
| --gui_spam_filter_capabilities_enabled &lt;booleanvalue&gt;<br />
|GUI_Spam_filter_capabilities_enabled<br />
|-<br />
| --defaultsenderaddress&lt;string&gt;<br />
|DefaultSenderAddress<br />
|-<br />
| --title &lt;string&gt;<br />
|Title<br />
|-<br />
| --position &lt;string&gt;<br />
|Position<br />
|-<br />
| --access-calendar<br />
&lt;on/off&gt;<br />
|Calendar module (Default is off)<br />
|-<br />
| --access-contacts &lt;on/off&gt;<br />
|Contact module access (Default is on)<br />
|-<br />
| --access-delegate-tasks &lt;on/off&gt;<br />
|Delegate tasks access (Default is off)<br />
|-<br />
| --access-edit-public-folder &lt;on/off&gt;<br />
|Edit public folder access (Default is off)<br />
|-<br />
| --access-ical &lt;on/off&gt;<br />
|Ical module access (Default is off)<br />
|-<br />
| --access-infostore &lt;on/off&gt;<br />
|Infostore module access (Default is off)<br />
|-<br />
| --access-read-create-shared-Folders &lt;on/off&gt;<br />
|Read create shared folder access (Default is off)<br />
|-<br />
| --access-syncml &lt;on/off&gt;<br />
|Syncml access (Default is off)<br />
|-<br />
| --access-active-sync &lt;on/off&gt;<br />
|Exchange Active Sync access (Default is off)<br />
|-<br />
| --access-usm &lt;on/off&gt;<br />
|Universal Sync Module access (Default is off)<br />
|-<br />
| --access-tasks &lt;on/off&gt;<br />
|Tasks access (Default is off)<br />
|-<br />
| --access-vcard &lt;on/off&gt;<br />
|Vcard access (Default is off)<br />
|-<br />
| --access-webdav &lt;on/off&gt;<br />
|Webdav access (Default is off)<br />
|-<br />
| --access-webdav-xml &lt;on/off&gt;<br />
|Webdav-Xml access (Default is off)<br />
|-<br />
| --access-webmail &lt;on/off&gt;<br />
|Webmail access (Default is on)<br />
|-<br />
| --access-publication &lt;on/off&gt;<br />
|Publication permission (Default is on). Note: access-publication needs access-infostore and is optional for Groupware+ and premium<br />
|-<br />
| --access-subscription &lt;on/off&gt;<br />
|Subscription permission (Default is on)<br />
|-<br />
| --access-edit-group &lt;on/off&gt;<br />
|Edit group access (Default is off)<br />
|-<br />
| --access-edit-resource &lt;on/off&gt;<br />
|Edit resource access (Default is off)<br />
|-<br />
| --access-edit-password &lt;on/off&gt;<br />
|Edit password access (Default is off)<br />
|-<br />
| --access-collect-email-addresses &lt;on/off&gt;<br />
|Edit collect email addresses (Default is off)<br />
|-<br />
| --access-multiple-mail-accounts &lt;on/off&gt;<br />
|Use multiple mail account feature (Default is off)<br />
|-<br />
| --access-global-address-book-disabled &lt;on/off&gt;<br />
|Access to global address book (Default is off). Note: Setting this option to true is only allowed in combination with PIM and Webmail rights. Note: There is a 'restoregaddefaults' script to restore the default permissions of the global address book folder. <br />
|-<br />
| --access--voipnow &lt;on/off&gt;<br />
|Access to VoiceOverIP feature.<br />
|-<br />
| --access-public-folder-editable &lt;on/off&gt;<br />
|Access to public folders. Allows or denies to see public folders. <br />
|-<br />
| --foldertree &lt;0/1&gt;<br />
|0 sets the OX standard folder tree and 1 sets the Outlook-like folder tree. <br />
|-<br />
| --access-olox20 &lt;on/off&gt;<br />
| Access to Olox2.0<br />
|}<br />
<br />
=== Access changes for existing users ===<br />
<br />
Changes to module access must be done for all users in a given context. On downgrade i. e., to revoke former given access, the data for objects will still be present in the database and on the filestore but is not visible to the customer any more. Please note that only the specified modules are changed. That is why it is required to explicitly turn modules off. A list of packages and the required module configuration is provided in [[the section called “Package access configuration”]].<br />
<br />
<br />
=== Extra parameters when authentication is enabled ===<br />
<br />
{| border="1"<br />
|-<br />
|-A,--adminuser &lt;string&gt;<br />
|Context Admin user name<br />
|-<br />
|-P,--adminpass &lt;string&gt;<br />
|Context Admin password<br />
|}<br />
<br />
=== Return value ===<br />
<br />
<code>0</code> on success<br />
<br />
<br />
<code>&gt;0</code> on failure<br />
<br />
<br />
=== Mandatory parameters ===<br />
<br />
'''<code>contextid {adminuser adminpass} (userid or username) and at minimum one attribute to change</code>'''<br />
<br />
primaryMail, Email1 and defaultSenderAddress must be present in set of aliases i. e., whenever you want to change one of<br />
* --email<br />
* --email1<br />
* --defaultsenderaddress<br />
you MUST take care, that the address you want to set is already contained in the aliases of the user.<br />
<br />
<br />
So when user has aliases: foo, bar and you want to change email to anotheraddr, you<br />
must add anotheraddr to the aliases, first.<br />
<br />
<br />
If needed, this can be done with one commandline call, e.g.:<br />
<br />
<br />
'''<code>/changeuser -A oxadmin -P secret -c 666 -i 4 -e<br />
anotheraddr -a foo,bar,anotheraddr</code>'''<br />
<br />
=== Command output ===<br />
<br />
On success:<br />
<br />
<br />
<code>user &lt;userid&gt; in &lt;contextid&gt; changed</code><br />
<br />
<br />
On failure:<br />
<br />
<br />
<code>user<br />
&lt;userid&gt; in &lt;contextid&gt; could not be changed: &lt;reason from server&gt;</code><br />
<br />
<br />
=== Example ===<br />
<br />
<code>root@oxhe~#</code>'''<code> changeuser -c 123 -i 3 -p newpwd</code>'''<br />
<br />
<br />
<code>user 3 in context 123 changed</code><br />
<br />
<br />
<br />
<br />
[[Category: Administrator]]<br />
<br />
[[Category: AppSuite]]<br />
[[Category: AdminGuide]]<br />
[[Category: CommandLineTools]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:DB_user_privileges&diff=20580AppSuite:DB user privileges2015-09-29T07:32:54Z<p>Martin.schneider: </p>
<hr />
<div>{{VersionFrom|7.8.0}}<br />
<br />
<div class="title">How to reduce Open-Xchange database user privileges for existing installations</div><br />
<br />
'''Summary''': This article tells you how to reduce the database user privileges in existing Open-Xchange installations to those at least required ones. Changing the existing <code>ALL PRIVILEDGES</code> to the provided minimum set will have no implications for running the server.<br />
<br />
The minimum required set of privileges is: CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, ALTER ROUTINE, CREATE ROUTINE, EXECUTE and SHOW DATABASES.<br />
<br />
Starting with v7.8.0 the following privileges are required: CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW and SHOW DATABASES.<br />
<br />
__TOC__<br />
<br />
== Change of existing privileges ==<br />
1. Login to master mysql database using root user.<br />
<br />
2. Detect the existing Open-Xchange users: <code><pre>SELECT USER,HOST FROM mysql.user;</pre></code><br />
<br />
The output will look like outlined in the following table:<br />
<br />
<code><pre><br />
+------------------+-----------+<br />
| user | host |<br />
+------------------+-----------+<br />
| openexchange | % |<br />
| root | 127.0.0.1 |<br />
</pre></code><br />
<br />
In this case the user for all additional processings is 'openexchange'@'%' and will be used for the description below.<br />
<br />
3. Detect all existing privileges for the Open-Xchange user above: <code><pre>SHOW GRANTS FOR 'openexchange'@'%';</pre></code><br />
<br />
The output will look like outlined in the following table. If the output is extremly different the user already has got limited privileges.<br />
<br />
<code><pre><br />
+---------------------------------------------------------------------------------------------------+<br />
| Grants for openexchange@% |<br />
+---------------------------------------------------------------------------------------------------+<br />
| GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'%' IDENTIFIED BY PASSWORD<br />
'*ef14c45205444fdd47b6c1d88b74e1345fd0c394' |<br />
+---------------------------------------------------------------------------------------------------+<br />
1 row in set (0,00 sec)<br />
</pre></code><br />
<br />
4. Revoke all existing privileges for the Open-Xchange user above. Be careful to use the database@host pattern provided by the output from #3 (in this case *.*): <code><pre>REVOKE ALL PRIVILEGES ON *.* FROM 'openexchange'@'%';</pre></code><br />
<br />
Hint: This must be executed for each database@hostname combination displayed in #3 (normally just *.*). Without revoking privileges you will have duplicates.<br />
<br />
5. Create new privileges: <code><pre>GRANT CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, SHOW DATABASES ON *.* TO 'openexchange'@'%' IDENTIFIED BY '<YOUR_DB_PASS>' WITH GRANT OPTION;</pre></code> <br />
<br />
<br />
6. Write the privileges: <code><pre>FLUSH PRIVILEGES;</pre></code><br />
<br />
7. The changes of the privileges are noticed by the server so that the grant tables are loaded into memory again immediately after the change. You do not have to restart mysql.<br />
<br />
The grants outlined by <code><pre>SHOW GRANTS FOR 'openexchange'@'%';</pre></code> should now look like (grants for configdb, schema, global db, guard db and guard shard available): <br />
<br />
<code><pre><br />
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+<br />
| Grants for openexchange@% |<br />
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+<br />
| GRANT USAGE ON *.* TO 'openexchange'@'%' IDENTIFIED BY PASSWORD '*ef14c45205444fdd47b6c1d88b74e1345fd0c394' |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `configdb`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxdatabase_6`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxdatabase_global`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxguard1`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxguard`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+<br />
</pre></code><br />
<br />
8. Execute<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]<br />
[[Category: Database]]<br />
[[Category: Security]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:DB_user_privileges&diff=20579AppSuite:DB user privileges2015-09-29T07:32:10Z<p>Martin.schneider: </p>
<hr />
<div>{{VersionFrom|7.8.0}}<br />
<br />
<div class="title">How to reduce Open-Xchange database user privileges for existing installations</div><br />
<br />
'''Summary''': This article tells you how to reduce the database user privileges in existing Open-Xchange installations to those at least required ones. Changing the existing <code>ALL PRIVILEDGES</code> to the provided minimum set will have no implications for running the server.<br />
<br />
The minimum required set of privileges is: CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, ALTER ROUTINE, CREATE ROUTINE, EXECUTE and SHOW DATABASES.<br />
<br />
Starting with v7.8.0 the following privileges are required: CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW and SHOW DATABASES.<br />
<br />
__TOC__<br />
<br />
== Change of existing privileges ==<br />
1. Login to master mysql database using root user.<br />
<br />
2. Detect the existing Open-Xchange users: <code><pre>SELECT USER,HOST FROM mysql.user;</pre></code><br />
<br />
The output will look like outlined in the following table:<br />
<br />
<code><pre><br />
+------------------+-----------+<br />
| user | host |<br />
+------------------+-----------+<br />
| openexchange | % |<br />
| root | 127.0.0.1 |<br />
</pre></code><br />
<br />
In this case the user for all additional processings is 'openexchange'@'%' and will be used for the description below.<br />
<br />
3. Detect all existing privileges for the Open-Xchange user above: <code><pre>SHOW GRANTS FOR 'openexchange'@'%';</pre></code><br />
<br />
The output will look like outlined in the following table. If the output is extremly different the user already has got limited privileges.<br />
<br />
<code><pre><br />
+---------------------------------------------------------------------------------------------------+<br />
| Grants for openexchange@% |<br />
+---------------------------------------------------------------------------------------------------+<br />
| GRANT ALL PRIVILEGES ON *.* TO 'openexchange'@'%' IDENTIFIED BY PASSWORD<br />
'*ef14c45205444fdd47b6c1d88b74e1345fd0c394' |<br />
+---------------------------------------------------------------------------------------------------+<br />
1 row in set (0,00 sec)<br />
</pre></code><br />
<br />
4. Revoke all existing privileges for the Open-Xchange user above. Be careful to use the database@host pattern provided by the output from #3 (in this case *.*): <code><pre>REVOKE ALL PRIVILEGES ON *.* FROM 'openexchange'@'%';</pre></code><br />
<br />
Hint: This must be executed for each database@hostname combination displayed in #3 (normally just *.*). Without revoking privileges you will have duplicates.<br />
<br />
5. Create new privileges: <code><pre>GRANT CREATE, LOCK TABLES, REFERENCES, INDEX, DROP, DELETE, ALTER, SELECT, UPDATE, INSERT, CREATE TEMPORARY TABLES, SHOW VIEW, SHOW DATABASES ON *.* TO 'openexchange'@'%' IDENTIFIED BY '<YOUR_DB_PASS>' WITH GRANT OPTION;</pre></code> <br />
<br />
<br />
6. Write the privileges: <code><pre>FLUSH PRIVILEGES;</pre></code><br />
<br />
7. The changes of the privileges are noticed by the server so that the grant tables are loaded into memory again immediately after the change. You do not have to restart mysql.<br />
<br />
The grants outlined by <code><pre>SHOW GRANTS FOR 'openexchange'@'%';</pre></code> should now look like (grants for configdb, schema, global db, guard db and guard shard available): <br />
<br />
<code><pre><br />
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+<br />
| Grants for openexchange@% |<br />
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+<br />
| GRANT USAGE ON *.* TO 'openexchange'@'%' IDENTIFIED BY PASSWORD '*14E65567ABDB5135D0CFD9A70B3032C179A49EE7' |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `configdb`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxdatabase_6`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxdatabase_global`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxguard1`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
| GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, REFERENCES, INDEX, ALTER, CREATE TEMPORARY TABLES, LOCK TABLES, SHOW VIEW ON `oxguard`.* TO 'openexchange'@'%' WITH GRANT OPTION |<br />
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+<br />
<br />
</pre></code><br />
<br />
8. Execute<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]<br />
[[Category: Database]]<br />
[[Category: Security]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Sharing_and_Guest_Mode&diff=20559AppSuite:Sharing and Guest Mode2015-09-23T14:23:21Z<p>Martin.schneider: </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 />
'''''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 &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 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 publications or subscriptions can be created by default<br />
* The web client does no longer give the option to publish or subscribe something<br />
* Existing publications / subscriptions can't be updated<br />
* Existing 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 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 subscriptions via HTTP-API may be configured via <code>com.openexchange.publish.createModifyEnabled</code> in file <code>subscribe.properties</code><br />
<br />
<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Drop_Stored_Procedures&diff=20429AppSuite:Drop Stored Procedures2015-09-14T09:23:06Z<p>Martin.schneider: </p>
<hr />
<div>{{VersionFrom|7.8.0}}<br />
<br />
<div class="title">Remove obsolete MySQL Stored Procedures from databases</div><br />
<br />
'''Summary''': This article tells you why and how to remove already existing but obsolete MySQL Stored Procedures from the various databases.<br />
<br />
__TOC__<br />
<br />
== Why to manually remove the existing Stored Procedures? ==<br />
<br />
The Stored Procedures mentioned within the next paragraph aren't needed any more by the Open-Xchange groupware. Because of the reduced privileges Open Xchange recommends with version 7.8.0 (see [[AppSuite:DB_user_privileges]] for more information) introduced due to security reasons the existing 'openexchange' database user isn't able to detect the existing Stored Procedures.<br />
<br />
== Which Stored Procedures are affected? ==<br />
<br />
The following Stored Procedures have to be removed from your configured config database:<br />
<br />
<code><pre>get_context_id, get_configdb_id</pre></code><br />
<br />
The following Stored Procedures have to be removed from the context schematas:<br />
<br />
<code><pre>get_attachment_id, get_calendar_id, get_contact_id, get_folder_id, get_forum_id, get_gid_number_id, get_gui_setting_id, get_ical_id, get_infostore_id, get_mail_service_id, get_pinboard_id, get_principal_id, get_project_id, get_resource_group_id, get_resource_id, get_task_id, get_uid_number_id, get_unique_id, get_webdav_id</pre></code><br />
<br />
== How to remove affected Stored Procedures? ==<br />
<br />
As there seem to be no routine to remove multiple Stored Procedures for MySQL you have to remove the mentioned procedures one by one. Because of this please execute the following statements with a database user having the appropriate privileges for each procedure that should be removed. Consider executing the command on the correct database (config vs. context db).<br />
<br />
<code><pre><br />
DROP PROCEDURE <THE_PROCEDURE_NAME>; <br />
</pre></code><br />
<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]<br />
[[Category: Database]]<br />
[[Category: Security]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Drop_Stored_Procedures&diff=20428AppSuite:Drop Stored Procedures2015-09-14T08:54:50Z<p>Martin.schneider: </p>
<hr />
<div>{{VersionFrom|7.8.0}}<br />
<br />
<div class="title">Remove obsolete MySQL Stored Procedures from databases</div><br />
<br />
'''Summary''': This article tells you why and how to remove already existing but obsolete MySQL Stored Procedures from the various databases.<br />
<br />
__TOC__<br />
<br />
== Why to manually remove the existing Stored Procedures? ==<br />
<br />
The Stored Procedures mentioned within the next paragraph aren't needed any more by the Open-Xchange groupware. Because of the reduced privileges Open Xchange recommends with version 7.8.0 (see [[AppSuite:DB_user_privileges]] for more information) introduced due to security reasons the existing 'openexchange' database user isn't able to detect the existing Stored Procedures.<br />
<br />
== Which Stored Procedures are affected? ==<br />
<br />
The following Stored Procedures have to be removed from your configured config database:<br />
<br />
* <code><pre>get_context_id, get_configdb_id</pre></code><br />
<br />
The following Stored Procedures have to be removed from the context schematas:<br />
<br />
* <code><pre>get_attachment_id, get_calendar_id, get_contact_id, get_folder_id, get_forum_id, get_gid_number_id, get_gui_setting_id, get_ical_id, get_infostore_id, get_mail_service_id, get_pinboard_id, get_principal_id, get_project_id, get_resource_group_id, get_resource_id, get_task_id, get_uid_number_id, get_unique_id, get_webdav_id</pre></code><br />
<br />
== How to remove affected Stored Procedures? ==<br />
<br />
As there seem to be no routine to remove multiple Stored Procedures for MySQL you have to remove the mentioned procedures one by one. Because of this please execute the following statements with a database user having the appropriate privileges for each procedure that should be removed. Consider executing the command on the correct database (config vs. context db).<br />
<br />
<code><pre><br />
DROP PROCEDURE <THE_PROCEDURE_NAME>; <br />
</pre></code><br />
<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]<br />
[[Category: Database]]<br />
[[Category: Security]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Drop_Stored_Procedures&diff=20427AppSuite:Drop Stored Procedures2015-09-14T08:53:57Z<p>Martin.schneider: </p>
<hr />
<div>{{VersionFrom|7.8.0}}<br />
<br />
<div class="title">Remove obsolete MySQL Stored Procedures from databases</div><br />
<br />
'''Summary''': This article tells you why and how to remove already existing but obsolete MySQL Stored Procedures from the various databases.<br />
<br />
__TOC__<br />
<br />
== Why to manually remove the existing Stored Procedures? ==<br />
<br />
The Stored Procedures mentioned within the next paragraph aren't needed any more by the Open-Xchange groupware. Because of the reduced privileges Open Xchange recommends with version 7.8.0 (see [[AppSuite:DB_user_privileges]] for more information) introduced due to security reasons the existing 'openexchange' database user isn't able to detect the existing Stored Procedures.<br />
<br />
== Which Stored Procedures are affected? ==<br />
<br />
The following Stored Procedures have to be removed from your configured config database:<br />
<br />
* get_context_id, get_configdb_id<br />
<br />
The following Stored Procedures have to be removed from the context schematas:<br />
<br />
* get_attachment_id, get_calendar_id, get_contact_id, get_folder_id, get_forum_id, get_gid_number_id, get_gui_setting_id, get_ical_id, get_infostore_id, get_mail_service_id, get_pinboard_id, get_principal_id, get_project_id, get_resource_group_id, get_resource_id, get_task_id, get_uid_number_id, get_unique_id, get_webdav_id<br />
<br />
== How to remove affected Stored Procedures? ==<br />
<br />
As there seem to be no routine to remove multiple Stored Procedures for MySQL you have to remove the mentioned procedures one by one. Because of this please execute the following statements with a database user having the appropriate privileges for each procedure that should be removed. Consider executing the command on the correct database (config vs. context db).<br />
<br />
DROP PROCEDURE <THE_PROCEDURE_NAME>; <br />
<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]<br />
[[Category: Database]]<br />
[[Category: Security]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:Drop_Stored_Procedures&diff=20426AppSuite:Drop Stored Procedures2015-09-14T08:38:34Z<p>Martin.schneider: Created page with "{{VersionFrom|7.8.0}} <div class="title">Remove obsolete MySQL Stored Procedures from databases</div> '''Summary''': This article tells you why and how to remove already exi..."</p>
<hr />
<div>{{VersionFrom|7.8.0}}<br />
<br />
<div class="title">Remove obsolete MySQL Stored Procedures from databases</div><br />
<br />
'''Summary''': This article tells you why and how to remove already existing but obsolete MySQL Stored Procedures from the various databases.<br />
<br />
__TOC__<br />
<br />
== Why to manually remove the existing Stored Procedures? ==<br />
<br />
The Stored Procedures mentioned within the next paragraph aren't needed any more by the Open-Xchange groupware. Because of the reduced privileges Open Xchange recommends with version 7.8.0 (see [[AppSuite:DB_user_privileges]] for more information) introduced due to security reasons the existing 'openexchange' database user isn't able to detect the existing Stored Procedures.<br />
<br />
== Which Stored Procedures are affected? ==<br />
<br />
The following Stored Procedures have to be removed from your configured config database:<br />
<br />
* get_context_id, get_configdb_id<br />
<br />
The following Stored Procedures have to be removed from the context schematas:<br />
<br />
* get_attachment_id, get_calendar_id, get_contact_id, get_folder_id, get_forum_id, get_gid_number_id, get_gui_setting_id, get_ical_id, get_infostore_id, get_mail_service_id, get_pinboard_id, get_principal_id, get_project_id, get_resource_group_id, get_resource_id, get_task_id, get_uid_number_id, get_unique_id, get_webdav_id<br />
<br />
== How to remove affected Stored Procedures? ==<br />
<br />
To remove the obsolete Stored Procedures please execute the following statements with a database user having the appropriate privileges.<br />
<br />
DROP PROCEDURE get_configdb_id; <br />
<br />
<br />
[[Category: OX7]]<br />
[[Category: AppSuite]]<br />
[[Category: Administrator]]<br />
[[Category: Database]]<br />
[[Category: Security]]</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20388HTTP API2015-09-10T12:25:50Z<p>Martin.schneider: /* Module "passwordchange" */</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 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>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=20224HTTP API2015-08-20T08:36:27Z<p>Martin.schneider: SCR 2657</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 />
<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>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=HTTP_API&diff=19939HTTP API2015-07-15T08:45:07Z<p>Martin.schneider: US 95838076, respond with json instead of redirect if desired</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 "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 "guest" or "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 "guest" and "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry || 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.<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 />
== 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 />
| 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 "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 "guest" or "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 "guest" and "anonymous" entities.<br />
|-<br />
| password || String || The optionally set password for "anonymous" entities.<br />
|-<br />
| expiry || 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 />
== 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 />
Existing shares can be accessed via different actions in the "share/management" module. <br />
<br />
=== Get all shares ===<br />
<br />
GET <code>/ajax/share/management?action=all</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 list all shares for.<br />
<br />
Response with timestamp: An array with share data. Each array element is a JSON object as described Share Info.<br />
<br />
{| id="ShareInfo" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Info<br />
! Name !! Type !! Value<br />
|-<br />
| share_url || String || The URL to access the share.<br />
|-<br />
| token || String || The (fully qualified) token of the share target.<br />
|-<br />
| authentication || String || The authentication type used to access the share, one of ''guest_password'', ''anonymous'' or ''anonymous_password''. <br />
|-<br />
| created || Time || The time the share was created. <br />
|-<br />
| created_by || Number || The identifier of the user who created the share. <br />
|-<br />
| last_modified || Time || The time the share was last modified. <br />
|-<br />
| modified_by || Time || The identifier of the user who modified the share. <br />
|-<br />
| target || Object || The share target as described in Share Target <br />
|-<br />
| recipient || Object || Information about the recipient of the share, i.e. the guest user, as described in Share Recipient <br />
|}<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 />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible. Must be given in milliseconds after 01-01-1970 in the users time zone or the time zone contained as URL parameter <br />
|-<br />
| meta || JSON || Stores arbitrary JSON data as specified by client. <br />
|}<br />
<br />
{| id="ShareRecipient" cellspacing="0" border="1"<br />
|+ align="bottom" | Share Recipient<br />
! Name !! Type !! Value<br />
|-<br />
| type || String || The recipient type, one of ''guest'' or ''anonymous''. <br />
|-<br />
| base_token || String || The base token associated with the guest user. <br />
|-<br />
| password || String || The password to access the share, in case the used authentication mode is ''anonymous_password''. <br />
|-<br />
| email_address || String || The email address of the named guest user, in case the recipient type is ''guest''. <br />
|-<br />
| entity || Number || The identifier of the underlying guest user entity. <br />
|}<br />
<br />
=== Get a share ===<br />
<br />
GET <code>/ajax/share/management?action=get</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>token</code> – The (fully qualified) token of the share.<br />
<br />
Response with timestamp: A JSON object as described in Share Info.<br />
<br />
=== Delete shares ===<br />
<br />
PUT <code>/ajax/share/management?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 containing the tokens of the shares to delete.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<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: A JSON object describing the shares to be created as described in Get a link. It contains an array holding the share "targets" as well as some properties of the guest user to be created.<br />
<br />
Response with timestamp: Basic information about the created share as described in GetALinkResponse.<br />
<br />
{| id="GetALink" cellspacing="0" border="1"<br />
|+ align="bottom" | Get a link<br />
! Name !! Type !! Value<br />
|-<br />
| targets || Array || An array of objects as described in Share Target <br />
|-<br />
| bits || Number || (Optional) A number as described in Permission flags. For single items, the bits for reading, writing and deleting objects in folders are taken into account. At least one of those must grant permissions to all objects, not only own ones. The highest value will be chosen based on the following sequence: delete all > write all > read all. If not set, only read permissions are granted. <br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share <br />
|}<br />
<br />
{| id="GetALinkResponse" cellspacing="0" border="1"<br />
|+ align="bottom" | Get a link response<br />
! Name !! Type !! Value<br />
|-<br />
| url || String || The link to the share<br />
|-<br />
| token || String || The share token as a reference for consecutive requests <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 share to be updated. Used to detect concurrent modifications.<br />
<br />
Request body: A JSON object describing the share to be updated as described in UpdateALink.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
{| id="UpdateALink" cellspacing="0" border="1"<br />
|+ align="bottom" | Update a link<br />
! Name !! Type !! Value<br />
|-<br />
| token || String || The token of the share to update<br />
|-<br />
| expiry_date || Time || (Optional) The end date / expiration time after which the share link is no longer accessible. Must be given in milliseconds after 01-01-1970 in the users time zone or the time zone contained as URL parameter.<br />
|-<br />
| password || String || (Optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| bits || Number || (Optional) A number as described in Permission flags. For single items, the bits for reading, writing and deleting objects in folders are taken into account. At least one of those must grant permissions to all objects, not only own ones. The highest value will be chosen based on the following sequence: delete all > write all > read all. If not set, only read permissions are granted.<br />
|-<br />
| meta || JSON || Stores arbitrary JSON data as specified by client<br />
|}<br />
<br />
=== Delete a link ===<br />
<br />
GET <code>/ajax/share/management?action=deleteLink</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
* <code>token</code> – The token of the share to delete.<br />
<br />
Response with timestamp: An empty JSON result in case of no errors.<br />
<br />
=== Invite ===<br />
<br />
PUT <code>/ajax/share/management?action=invite</code><br />
<br />
Parameters:<br />
* <code>session</code> – A session ID previously obtained from the login module.<br />
<br />
Request body: A JSON object representing the shares to be created as described in Invite Data.<br />
<br />
Response with timestamp: An array of share tokens for all created external recipients. The tokens are in the same order as the recipients in the request array. For internal users and groups a NULL value is set in the array.<br />
<br />
{| id="InviteData" cellspacing="0" border="1"<br />
|+ align="bottom" | Invite data<br />
! Name !! Type !! Value<br />
|-<br />
| targets || Array || An array of objects as described in Share Target <br />
|-<br />
| recipients || Array || An array of objects as described in Invited Recipient<br />
|-<br />
| message || String || (Optional) A custom message that will be contained in the notification mails for guests with mail addresses and password.<br />
|}<br />
<br />
{| id="InvitedRecipient" cellspacing="0" border="1"<br />
|+ align="bottom" | Invited recipient<br />
! Name !! Type !! Value<br />
|-<br />
| type || String || The recipient type, i.e. one of "user", "group", "guest", "anonymous"<br />
|-<br />
| bits || Number || A number as described in Permission flags. For single items, the bits for reading, writing and deleting objects in folders are taken into account. At least one of those must grant permissions to all objects, not only own ones. The highest value will be chosen based on the following sequence: delete all > write all > read all.<br />
|-<br />
| entity || Number || (for type "user" or "group") The user or group identifier of the recipient<br />
|-<br />
| password || String || (for type "anonymous", optional) An additional secret / pin number an anonymous user needs to enter when accessing the share<br />
|-<br />
| email_address || String || (for type "guest") The e-mail address of the recipient<br />
|-<br />
| display_name || String || (for type "guest", optional) The display name of the recipient<br />
|-<br />
| contact_id || String || (for type "guest", optional) The object identifier of the corresponding contact entry if the recipient was chosen from the address book<br />
|-<br />
| contact_folder || String || (for type "guest", required if "contact_id" is set) The folder identifier of the corresponding contact entry if the recipient was chosen from the address book<br />
|}<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 />
|}</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=19926OXReportClient2015-07-14T06:32:43Z<p>Martin.schneider: /* Explanation of the old console output */</p>
<hr />
<div>== Introduction ==<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Report kinds ===<br />
<br />
In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination. <br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of the appsuite report console output ===<br />
<br />
<pre><br />
$ /opt/open-xchange/sbin/report -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %) <br />
UUID: f5f511d663ff462f8f963dfa41bd8cd2<br />
Type: default<br />
Total time: 389 milliseconds<br />
Avg. time per context: 77 milliseconds<br />
Report was finished: Wed Jul 08 13:42:25 CEST 2015<br />
<br />
------ report -------<br />
{<br />
"macdetail" : {<br />
"capabilitySets" : [ {<br />
"total" : 2,<br />
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 0,<br />
"disabled" : 0<br />
}, {<br />
"total" : 11,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 3,<br />
"disabled" : 0<br />
}, {<br />
"total" : 6,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 2,<br />
"disabled" : 0<br />
} ]<br />
},<br />
"total" : {<br />
"guests" : 22,<br />
"links" : 10,<br />
"contexts" : 5,<br />
"users" : 19,<br />
"report-format" : "appsuite-short"<br />
},<br />
"clientlogincountyear" : {<br />
"appsuite" : "7",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "9",<br />
"carddav" : "1"<br />
},<br />
"clientlogincount" : {<br />
"appsuite" : "4",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "2",<br />
"carddav" : "1"<br />
},<br />
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",<br />
"reportType" : "default",<br />
"timestamps" : {<br />
"start" : 1436355744714,<br />
"stop" : 1436355745103<br />
},<br />
"version" : {<br />
"version" : "7.8.0-Rev0",<br />
"buildDate" : "develop"<br />
},<br />
"configs" : {<br />
"com.openexchange.mail.adminMailLoginEnabled" : "true"<br />
}<br />
}<br />
------ end -------<br />
</pre><br />
<br />
'''macdetail:'''<br />
: detailed information about existing module access combinations and its usage <br />
'''total:'''<br />
: accumulated user, guest, link (anonymous share) and context count<br />
'''clientlogincountyear:'''<br />
: number of client logins for the last year<br />
'''clientlogincount:'''<br />
: number of client logins for the last month<br />
'''uuid:'''<br />
: a unique id for the report<br />
'''reportType:'''<br />
: given name for that report (normally 'default')<br />
'''timestamps:'''<br />
: timestamps of the start and end time of the report<br />
'''versions:'''<br />
: version and build date of the server<br />
'''configs:'''<br />
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')<br />
<br />
=== Explanation of the old console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -o -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users guests links'''<br />
5 19 22 10 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''key value'''<br />
com.openexchange.mail.adminMailLoginEnabled true <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''guests:'''<br />
:total number of guests<br />
'''linkss:'''<br />
:total number of links shared to anonymous users<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
'''key:'''<br />
:key of the configuration property<br />
'''value:'''<br />
:value of the configuration property<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id, capability sets<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=19925OXReportClient2015-07-14T06:30:07Z<p>Martin.schneider: /* Explanation of the old console output */</p>
<hr />
<div>== Introduction ==<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Report kinds ===<br />
<br />
In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination. <br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of the appsuite report console output ===<br />
<br />
<pre><br />
$ /opt/open-xchange/sbin/report -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %) <br />
UUID: f5f511d663ff462f8f963dfa41bd8cd2<br />
Type: default<br />
Total time: 389 milliseconds<br />
Avg. time per context: 77 milliseconds<br />
Report was finished: Wed Jul 08 13:42:25 CEST 2015<br />
<br />
------ report -------<br />
{<br />
"macdetail" : {<br />
"capabilitySets" : [ {<br />
"total" : 2,<br />
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 0,<br />
"disabled" : 0<br />
}, {<br />
"total" : 11,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 3,<br />
"disabled" : 0<br />
}, {<br />
"total" : 6,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 2,<br />
"disabled" : 0<br />
} ]<br />
},<br />
"total" : {<br />
"guests" : 22,<br />
"links" : 10,<br />
"contexts" : 5,<br />
"users" : 19,<br />
"report-format" : "appsuite-short"<br />
},<br />
"clientlogincountyear" : {<br />
"appsuite" : "7",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "9",<br />
"carddav" : "1"<br />
},<br />
"clientlogincount" : {<br />
"appsuite" : "4",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "2",<br />
"carddav" : "1"<br />
},<br />
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",<br />
"reportType" : "default",<br />
"timestamps" : {<br />
"start" : 1436355744714,<br />
"stop" : 1436355745103<br />
},<br />
"version" : {<br />
"version" : "7.8.0-Rev0",<br />
"buildDate" : "develop"<br />
},<br />
"configs" : {<br />
"com.openexchange.mail.adminMailLoginEnabled" : "true"<br />
}<br />
}<br />
------ end -------<br />
</pre><br />
<br />
'''macdetail:'''<br />
: detailed information about existing module access combinations and its usage <br />
'''total:'''<br />
: accumulated user, guest, link (anonymous share) and context count<br />
'''clientlogincountyear:'''<br />
: number of client logins for the last year<br />
'''clientlogincount:'''<br />
: number of client logins for the last month<br />
'''uuid:'''<br />
: a unique id for the report<br />
'''reportType:'''<br />
: given name for that report (normally 'default')<br />
'''timestamps:'''<br />
: timestamps of the start and end time of the report<br />
'''versions:'''<br />
: version and build date of the server<br />
'''configs:'''<br />
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')<br />
<br />
=== Explanation of the old console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -o -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users guests links'''<br />
5 19 22 10 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''guests:'''<br />
:total number of guests<br />
'''linkss:'''<br />
:total number of links shared to anonymous users<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id, capability sets<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=19924OXReportClient2015-07-14T06:28:16Z<p>Martin.schneider: /* Explanation of the appsuite report console output */</p>
<hr />
<div>== Introduction ==<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Report kinds ===<br />
<br />
In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination. <br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of the appsuite report console output ===<br />
<br />
<pre><br />
$ /opt/open-xchange/sbin/report -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %) <br />
UUID: f5f511d663ff462f8f963dfa41bd8cd2<br />
Type: default<br />
Total time: 389 milliseconds<br />
Avg. time per context: 77 milliseconds<br />
Report was finished: Wed Jul 08 13:42:25 CEST 2015<br />
<br />
------ report -------<br />
{<br />
"macdetail" : {<br />
"capabilitySets" : [ {<br />
"total" : 2,<br />
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 0,<br />
"disabled" : 0<br />
}, {<br />
"total" : 11,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 3,<br />
"disabled" : 0<br />
}, {<br />
"total" : 6,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 2,<br />
"disabled" : 0<br />
} ]<br />
},<br />
"total" : {<br />
"guests" : 22,<br />
"links" : 10,<br />
"contexts" : 5,<br />
"users" : 19,<br />
"report-format" : "appsuite-short"<br />
},<br />
"clientlogincountyear" : {<br />
"appsuite" : "7",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "9",<br />
"carddav" : "1"<br />
},<br />
"clientlogincount" : {<br />
"appsuite" : "4",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "2",<br />
"carddav" : "1"<br />
},<br />
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",<br />
"reportType" : "default",<br />
"timestamps" : {<br />
"start" : 1436355744714,<br />
"stop" : 1436355745103<br />
},<br />
"version" : {<br />
"version" : "7.8.0-Rev0",<br />
"buildDate" : "develop"<br />
},<br />
"configs" : {<br />
"com.openexchange.mail.adminMailLoginEnabled" : "true"<br />
}<br />
}<br />
------ end -------<br />
</pre><br />
<br />
'''macdetail:'''<br />
: detailed information about existing module access combinations and its usage <br />
'''total:'''<br />
: accumulated user, guest, link (anonymous share) and context count<br />
'''clientlogincountyear:'''<br />
: number of client logins for the last year<br />
'''clientlogincount:'''<br />
: number of client logins for the last month<br />
'''uuid:'''<br />
: a unique id for the report<br />
'''reportType:'''<br />
: given name for that report (normally 'default')<br />
'''timestamps:'''<br />
: timestamps of the start and end time of the report<br />
'''versions:'''<br />
: version and build date of the server<br />
'''configs:'''<br />
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')<br />
<br />
=== Explanation of the old console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -o -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users guests'''<br />
5 19 22 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''guests:'''<br />
:total number of guests<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id, capability sets<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=19891OXReportClient2015-07-08T12:15:11Z<p>Martin.schneider: /* What will be reported using the send method? */</p>
<hr />
<div>== Introduction ==<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Report kinds ===<br />
<br />
In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination. <br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of the appsuite report console output ===<br />
<br />
<pre><br />
$ /opt/open-xchange/sbin/report -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %) <br />
UUID: f5f511d663ff462f8f963dfa41bd8cd2<br />
Type: default<br />
Total time: 389 milliseconds<br />
Avg. time per context: 77 milliseconds<br />
Report was finished: Wed Jul 08 13:42:25 CEST 2015<br />
<br />
------ report -------<br />
{<br />
"macdetail" : {<br />
"capabilitySets" : [ {<br />
"total" : 2,<br />
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 0,<br />
"disabled" : 0<br />
}, {<br />
"total" : 11,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 3,<br />
"disabled" : 0<br />
}, {<br />
"total" : 6,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 2,<br />
"disabled" : 0<br />
} ]<br />
},<br />
"total" : {<br />
"guests" : 22,<br />
"contexts" : 5,<br />
"users" : 19,<br />
"report-format" : "appsuite-short"<br />
},<br />
"clientlogincountyear" : {<br />
"appsuite" : "7",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "9",<br />
"carddav" : "1"<br />
},<br />
"clientlogincount" : {<br />
"appsuite" : "4",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "2",<br />
"carddav" : "1"<br />
},<br />
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",<br />
"reportType" : "default",<br />
"timestamps" : {<br />
"start" : 1436355744714,<br />
"stop" : 1436355745103<br />
},<br />
"version" : {<br />
"version" : "7.8.0-Rev0",<br />
"buildDate" : "develop"<br />
},<br />
"configs" : {<br />
"com.openexchange.mail.adminMailLoginEnabled" : "true"<br />
}<br />
}<br />
------ end -------<br />
</pre><br />
<br />
'''macdetail:'''<br />
: detailed information about existing module access combinations and its usage <br />
'''total:'''<br />
: accumulated user, guest and context cound<br />
'''clientlogincountyear:'''<br />
: number of client logins for the last year<br />
'''clientlogincount:'''<br />
: number of client logins for the last month<br />
'''uuid:'''<br />
: a unique id for the report<br />
'''reportType:'''<br />
: given name for that report (normally 'default')<br />
'''timestamps:'''<br />
: timestamps of the start and end time of the report<br />
'''versions:'''<br />
: version and build date of the server<br />
'''configs:'''<br />
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')<br />
<br />
=== Explanation of the old console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -o -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users guests'''<br />
5 19 22 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''guests:'''<br />
:total number of guests<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id, capability sets<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=19890OXReportClient2015-07-08T12:03:43Z<p>Martin.schneider: US 97991458, set appsuite report as default and ensure/provide old functionality with '-o'</p>
<hr />
<div>== Introduction ==<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Report kinds ===<br />
<br />
In general there are two kinds of reports. Since 7.8.0 the default report has got the appsuite style format. If you would like to generate and display/save/send the formerly used style you have to add the option "-o" to every known parameter combination. <br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of the appsuite report console output ===<br />
<br />
<pre><br />
$ /opt/open-xchange/sbin/report -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
f5f511d663ff462f8f963dfa41bd8cd2: 0/5 (0,00 %) <br />
UUID: f5f511d663ff462f8f963dfa41bd8cd2<br />
Type: default<br />
Total time: 389 milliseconds<br />
Avg. time per context: 77 milliseconds<br />
Report was finished: Wed Jul 08 13:42:25 CEST 2015<br />
<br />
------ report -------<br />
{<br />
"macdetail" : {<br />
"capabilitySets" : [ {<br />
"total" : 2,<br />
"capabilities" : [ "auto_publish_attachments", "autologin", "caldav", "carddav", "drive", "infostore", "mailfilter", "oauth", "oauth-grants", "pop3", "printing", "publish_mail_attachments", "rss", "search", "twitter", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 0,<br />
"disabled" : 0<br />
}, {<br />
"total" : 11,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "filestore", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 3,<br />
"disabled" : 0<br />
}, {<br />
"total" : 6,<br />
"capabilities" : [ "active_sync", "auto_publish_attachments", "autologin", "caldav", "calendar", "carddav", "collect_email_addresses", "conflict_handling", "contacts", "delegate_tasks", "drive", "edit_password", "edit_public_folders", "edit_resource", "freebusy", "gab", "groupware", "ical", "infostore", "mailfilter", "mobility", "multiple_mail_accounts", "oauth", "oauth-grants", "olox20", "participants_dialog", "pim", "pop3", "portal", "printing", "publication", "publish_mail_attachments", "read_create_shared_folders", "rss", "search", "subscription", "tasks", "twitter", "usm", "vcard", "webdav", "webdav_xml", "webmail", "xing", "xingjson" ],<br />
"quota" : 1073741824,<br />
"admin" : 2,<br />
"disabled" : 0<br />
} ]<br />
},<br />
"total" : {<br />
"guests" : 22,<br />
"contexts" : 5,<br />
"users" : 19,<br />
"report-format" : "appsuite-short"<br />
},<br />
"clientlogincountyear" : {<br />
"appsuite" : "7",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "9",<br />
"carddav" : "1"<br />
},<br />
"clientlogincount" : {<br />
"appsuite" : "4",<br />
"olox2" : "0",<br />
"caldav" : "0",<br />
"usm-eas" : "0",<br />
"mobileapp" : "0",<br />
"ox6" : "2",<br />
"carddav" : "1"<br />
},<br />
"uuid" : "f5f511d663ff462f8f963dfa41bd8cd2",<br />
"reportType" : "default",<br />
"timestamps" : {<br />
"start" : 1436355744714,<br />
"stop" : 1436355745103<br />
},<br />
"version" : {<br />
"version" : "7.8.0-Rev0",<br />
"buildDate" : "develop"<br />
},<br />
"configs" : {<br />
"com.openexchange.mail.adminMailLoginEnabled" : "true"<br />
}<br />
}<br />
------ end -------<br />
</pre><br />
<br />
'''macdetail:'''<br />
: detailed information about existing module access combinations and its usage <br />
'''total:'''<br />
: accumulated user, guest and context cound<br />
'''clientlogincountyear:'''<br />
: number of client logins for the last year<br />
'''clientlogincount:'''<br />
: number of client logins for the last month<br />
'''uuid:'''<br />
: a unique id for the report<br />
'''reportType:'''<br />
: given name for that report (normally 'default')<br />
'''timestamps:'''<br />
: timestamps of the start and end time of the report<br />
'''versions:'''<br />
: version and build date of the server<br />
'''configs:'''<br />
: server configuration (currently only for setting 'com.openexchange.mail.adminMailLoginEnabled')<br />
<br />
=== Explanation of the old console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -o -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users guests'''<br />
5 19 22 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''guests:'''<br />
:total number of guests<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=19887OXReportClient2015-07-08T11:24:24Z<p>Martin.schneider: US 97991458, set appsuite report as default and ensure/provide old functionality with '-o'</p>
<hr />
<div>== Introduction ==<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of the old console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -o -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users guests'''<br />
5 19 22 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''guests:'''<br />
:total number of guests<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=OXReportClient&diff=19886OXReportClient2015-07-08T11:13:03Z<p>Martin.schneider: US 97991458, set appsuite report as default and ensure/provide old functionality with '-o'</p>
<hr />
<div>== Introduction ==<br />
<br />
Beginning with the release of Open-Xchange Server version 6.18, '''generating a report every month'''<br />
is mandatory in order to have access to the maintenance updates available in the updates directory<br />
on software.open-xchange.com.<br />
<br />
'''You have been blocked already?'''<br />
<br />
'''Don't panic''', you can still access http://software.open-xchange.com/OX6/stable, because that<br />
is open for everyone.<br />
So install the Report Client from stable instead of updates and once you're done, update to the latest version.<br />
<br />
The Open-Xchange Report Client extension of the Open-Xchange Server enables you to generate and send usage reports of your environment to Open-Xchange. The report will contain information of how many contexts and users have been created in the given Open-Xchange environment. This article will guide you through the installation of the Open-Xchange Report Client. It describes the setup of the software extension itself, and which additional configurations need to be done to execute this extension.<br />
<br />
You will find further information at the Open-Xchange Frequent Asked Questions (FAQ)<br />
* [http://sdb.open-xchange.com/faq/70 English]<br />
* [http://sdb.open-xchange.com/category/1/71 German]<br />
<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=updates}}<br />
<br />
{{InstallPlugin|pluginname=open-xchange-report-client|sopath=6.22/updates/backend|version=v6.22.x}}<br />
<br />
== Configuration ==<br />
<br />
A requirement to execute the Open-Xchange Report Client is to have your Open-Xchange license key stored in one specific file on your Open-Xchange installation. The latest version of our [[Main_Page#Installation_based_on_packages | installation guide]] documentation will automatically enable you to store your license key on disk by using a new oxinstaller command.<br />
<br />
If you want to use the report client on an already installed environment you need to store your license key manually on disk. To do so create and edit the following file on your Open-Xchange server:<br />
<br />
$ vim /opt/open-xchange/etc/common/licensekeys.properties <br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/licensekeys.properties <br />
<br />
com.openexchange.licensekey.1=PUT_YOUR_OPEN-XCHANGE_LICENSE_KEY_HERE<br />
<br />
If you are behind a firewall and the report client needs to be configured using a HTTP proxy, please edit file:<br />
<br />
$ vim /opt/open-xchange/etc/groupware/reportclient.properties<br />
<br />
or on 6.22 or newer<br />
<br />
$ vim /opt/open-xchange/etc/reportclient.properties<br />
<br />
After editing this file accordingly to your proxy needs, try to start the report client again.<br />
<br />
== Using the Report tool ==<br />
<br />
Now as the package has been correctly installed and you provided your license key in the according properties file your are ready to launch the report client to generate a report. By default (if no option is given) the report client will display and send the generated report to an Open-Xchange service on activation.open-xchange.com. Note that only data that is displayed in the console will be transfered to Open-Xchange <br />
<br />
'''activation.open-xchange.com:443'''<br />
<br />
=== Display data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
<br />
If you want to know which data would be transfered, execute the report client with the option "-d" (display_only). If this option is given to the report client no data will be send:<br />
<br />
=== Send data usage report ===<br />
<br />
$ /opt/open-xchange/sbin/report -s<br />
<br />
If you don't want to have the report displayed in the console (which might be the case for automated executions of the report client) execute the report client with the option -s (send_only). Now no report will be displayed after the report has been sent to activation.open-xchange.com.<br />
<br />
=== Available options ===<br />
<br />
$ /opt/open-xchange/sbin/report -h<br />
<br />
lists all available options:<br />
<br />
Usage: report<br />
-h,--help Prints a help text <br />
--environment Show info about commandline environment<br />
--nonl Remove all newlines (\n) from output<br />
--responsetimeout <responsetimeout> response timeout in seconds for reading response from<br />
the backend (default 0s; infinite)<br />
-H,--host <host> specifies the host <br />
-T,--timeout <timeout> timeout (in s) to conntect to the backend (default 15s)<br />
-J,--jmxauthuser <jmxauthuser> jmx username (when jmx authentication enabled)<br />
-P,--jmxauthpassword <jmxauthpassword> jmx password (when jmx authentication enabled)<br />
-s,--sendonly Send report without displaying it (Disables default)<br />
-d,--displayonly Display report without sending it (Disables default)<br />
-c,--csv Show output as CSV <br />
-a,--advancedreport Run an advanced report<br />
-f,--savereport Save the report as JSON String instead of sending it<br />
-b,--showaccesscombination <showaccesscombination> Show access combination for bitmask<br />
-e,--run-appsuite-report Schedule an appsuite style report<br />
-t,--report-type <report-type> The type of the report to run<br />
--inspect-appsuite-reports Prints information about currently running reports<br />
--cancel-appsuite-reports Cancels pending reports <br />
-g,--get-appsuite-report Retrieve the report that was generated<br />
-x,--run-and-deliver-report Create a new report and send it immediately<br />
-o,--run-and-deliver-old-report Run old report type. Used to have a backward compatibility.<br />
<br />
=== Explanation of console output ===<br />
<br />
$ /opt/open-xchange/sbin/report -d<br />
Starting the Open-Xchange report client. Note that the report generation may take a little while.<br />
<br />
module version <br />
admin 6.20.5 Rev1<br />
groupware 6.20.5 Rev1<br />
<br />
'''contexts users'''<br />
3 56 <br />
<br />
'''mac count adm disabled'''<br />
268435455 6 1 0 <br />
237044501 48 0 0 <br />
5 2 2 0 <br />
<br />
'''usmeas olox2 mobileapp carddav caldav'''<br />
1 0 0 0 0<br />
<br />
'''usmeasyear olox2year mobileappyear carddavyear caldavyear'''<br />
4 12 7 11 10 <br />
<br />
<br />
'''contexts:'''<br />
:total number of contexts<br />
'''users:'''<br />
:total number of users<br />
'''mac:'''<br />
:decimal value of the module access. For conversion decimal to human readable permission please use <tt>report -b</tt> as described below<br />
'''count:'''<br />
:amount of users with this module access<br />
'''adm:'''<br />
:amount of admin users with this specific module access<br />
'''disabled:'''<br />
:amount of users that are disabled<br />
<br />
The last rows show the amount of users that did login to Open-Xchange within the ''last 30 days'' and ''the last year'' using the specified OXtender/service.<br />
<br />
If you want to know the access permissions of a specific <tt>mac</tt>, run e.g.<br />
<br />
$ /opt/open-xchange/sbin/report -b 237044501<br />
<br />
'''usmeas:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last 30 days<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last 30 days<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last 30 days<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last 30 days<br />
'''usmeasyear:'''<br />
:using mobile phone via active sync (OXtender for Business Mobility) within the last year<br />
'''olox2:'''<br />
:using OXtender 2 for Microsoft Outlook within the last year<br />
'''mobileapp:'''<br />
:using Open-Xchange Mobile Web Interface within the last year<br />
'''carddav/caldav:'''<br />
:using the CalDAV/CardDAV feature within the last year<br />
<br />
'''Example:''' a value of 7 below <tt>olox2</tt> means, that within the last 30 days, 7 different users used the OXtender 2 for Microsoft Outlook to connect to Open-Xchange.<br />
<br />
== Automatic reports ==<br />
<br />
Creating a cron entry which will automatically execute the report client once a week saves a lot of work. To create this cron entry execute:<br />
<br />
$ vim /etc/cron.d/open-xchange_report<br />
<br />
0 3 * * 7 open-xchange /opt/open-xchange/sbin/report -s -x 1> /dev/null 2>&1<br />
<br />
== What will be reported using the send method? ==<br />
<br />
The report client will display and / or transfer the following information:<br />
<br />
# Version number of the Open-Xchange server package<br />
# Version number of the Open-Xchange admin package<br />
# Total user count<br />
# Total context count<br />
# Detailed context information: context age, creation date or date of creation, user count, context id<br />
# Detailed user information (per context): User access combination flags (which modules have been activated for the users)</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=Sandbox:OX_Tutorial_1M/sandbox&diff=19867Sandbox:OX Tutorial 1M/sandbox2015-07-07T13:11:09Z<p>Martin.schneider: US 97798972, remove everything related to facebook</p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
{{OX_HE_Tutorial_Design}}<br />
<br />
= Specific Sizing Recommendations =<br />
<br />
== Load Balancing ==<br />
No Loadbalancer is needed in front of the default balancing HTTP server.<br />
<br />
==Middleware==<br />
Can we realistically offer to host 10k mailboxes on a single server?<br />
<br />
===Groupware===<br />
1..x groupware hosts with *specific hardware requirements*<br />
<br />
===Documentconversion===<br />
1..x conversion hosts with *specific hardware requirements*<br />
<br />
===Synchronisation===<br />
1..x sync hosts with *specific hardware requirements*<br />
<br />
==Mail Server==<br />
Standalone or on one of the middleware hosts?<br />
<br />
==SQL Server==<br />
Single master or replicated? Standalone or on one of the middleware hosts?<br />
<br />
==File Server==<br />
Standalone or on one of the middleware hosts?<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-1M.png|1000px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== General recommendations ==<br />
<br />
* A virtualisation enviroment is recommended<br />
* Many machines with less memory (16 GB) are preferred to fewer machines with big memory<br />
* The picture above shows a valid setup for a webmail only system. Further features like the Business Mobility Connector or OX Documentes require more ressources.<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests (see [[Automated_GUI_Tests|here]])<br />
# Upsell Plugin (see [[AppSuite:Upsell|here]] and [[AppSuite:Upsell_tools|here]])<br />
# Automatic FailOver<br />
# Theming (see [[AppSuite:Theming|here]])<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Martin.schneiderhttps://oxpedia.org/wiki/index.php?title=AppSuite:OX_Tutorial_1M&diff=19866AppSuite:OX Tutorial 1M2015-07-07T13:10:43Z<p>Martin.schneider: US 97798972, remove everything related to facebook</p>
<hr />
<div>= Tutorial: High Available OX App Suite Setup for up to 1 Milion users =<br />
<br />
'''This article describes what you need for a typical OX App Suite Setup for up to 1.000.000 Users, which is fully clustered, high available and scaling very flexible.'''<br />
<br />
It contains everything you need to:<br />
* Understand the design of the OX App Suite setup including additional services<br />
* Install the whole system based on the relevant articles<br />
* Find pointers to the next steps of integration<br />
<br />
<br />
= System Design =<br />
<br />
[[Image:AppSuite-1M.png|1000px]]<br />
<br />
The system is designed to provide maximum functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is transparently handled by the load balancer. If one MySQL server fails, it is sufficient to take over the IP address on the other MySQL server in the cluster to stay fully in operation.<br />
<br />
== General recommendations ==<br />
<br />
* A virtualisation enviroment is recommended<br />
* Many machines with less memory (16 GB) are preferred to fewer machines with big memory<br />
* The picture above shows a valid setup for a webmail only system. Further features like the Business Mobility Connector or OX Documentes require more ressources.<br />
<br />
== Infrastructure Components not delivered by OX ==<br />
<br />
* An email system providing IMAP and SMTP<br />
* A control panel for creation and administration of users<br />
* A Load Balancer in front of the OX servers (optional, recommended)<br />
<br />
= Overview Installation Steps =<br />
<br />
'''To deploy the described OX setup, the following steps need to be done. '''<br />
<br />
<br />
== Mandatory Steps ==<br />
# Initialize and configure MySQL database servers<br />
# Install and configure OX on all servers<br />
<br />
== Steps depending on your environment ==<br />
# Implement Load Balancer<br />
# Connect Control Panel<br />
# Connect Email System<br />
<br />
== Recommended Optional Next Steps ==<br />
# Automated Frontend Tests (see [[Automated_GUI_Tests|here]])<br />
# Upsell Plugin (see [[AppSuite:Upsell|here]] and [[AppSuite:Upsell_tools|here]])<br />
# Automatic FailOver<br />
# Theming (see [[AppSuite:Theming|here]])<br />
<br />
= Mandatory Installation Steps - Instructions & Recommendations =<br />
<br />
<br />
'''The following steps need to be done in every case to get OX up and running:'''<br />
<br />
== Initialize and configure MySQL database on both servers ==<br />
<br />
MySQL will be configured as Master-Master configuration to ensure data consistency on both servers.<br />
If one machine fails, the other machine will take over all functionality.<br />
<br />
[[OXLoadBalancingClustering_Database|Database setup for clustered environments]]<br />
<br />
== Install and configure OX on both servers ==<br />
<br />
OX will be installed on minimum two servers. It will be configured to '''write''' to the '''first''' MySQL database and to '''read''' from the '''second''' MySQL database in one cluster. This will distribute the load during normal operation as smooth as possible. During FailOver the IP address of the failed MySQL server will be taken over to the working server, the system stays operable.<br />
<br />
[[AppSuite:OXLoadBalancingClustering_OXConfiguration|Open-Xchange setup and configuration for clustered environments]]<br />
<br />
The NFS server will be mounted on all machines and registered as filestore.<br />
<br />
[[OXLoadBalancingClustering_Filestore|Filestore setup for clustered environments]]<br />
<br />
When multiple Open-Xchange Servers are configured within a cluster Session and Loadbalancing needs to be set up.<br />
<br />
[[OXLoadBalancingClustering_SessionLoadbalancing|Session and Loadbalancing for clustered environments]]<br />
<br />
[[OXLoadBalancingClustering_NetworkConfiguration|Network configuration for clustered environments]]<br />
<br />
You also should install and configure the OXtender for Business Mobility:<br />
<br />
[[OXtender_for_Business_Mobility| exchange active sync configuration for Open-Xchange]]<br />
<br />
Let your users connect to their data from other services like Twitter or LinkedIn by configuring the "SocialOX"<br />
<br />
[[SocialOX|SocialOX-Configuration]]<br />
<br />
= Installation Steps depending on your environment - Instructions & Recommendations =<br />
<br />
'''The following components need to be implemented in your environment.'''<br />
<br />
<br />
== Implement Load Balancer ==<br />
<br />
A load balancer in front of the OX servers is necessary for this deployment size. It needs to handle the requests if one OX server fails.<br />
<br />
If you already have a hardware load balancing solution in place, this can be used. OX is known to work with the standard load balancing solutions from BigIP, Barracuda, Foundry, ...<br />
<br />
If you do not have a load balancing solution already in place, we recommend to use [http://www.keepalived.org/ Keepalived] as reliable and cost effective solution.<br />
<br />
Read more about configuring [[Keepalived | Keepalived for Open-Xchange]]<br />
<br />
<br />
{{OX_HE_Tutorial_CP}}<br />
<br />
<br />
{{OX_HE_Tutorial_HGP}}<br />
<br />
<br />
{{OX_HE_Tutorial_POA}}<br />
<br />
<br />
{{OX_HE_Tutorial_Auth}}<br />
<br />
== Connect Email System ==<br />
<br />
Every email system providing IMAP and SMTP can be used as backend to OX. Best experiences are made with the widespread Linux based IMAP servers [http://dovecot.org/ Dovecot], [http://www.cyrusimap.org/ Cyrus] or [http://www.courier-mta.org/imap/ Courier]. <br />
<br />
Other IMAP servers need to be tested thoroughly before going into production.<br />
<br />
There are several possibilities to implement the Email system:<br />
<br />
# You already have an email system available: Nothing needs to be done, it just needs to be configured<br />
# You use Parallels Automation (POA): Nothing special needs to be done, everything you need is contained in the APS package<br />
# You want to setup a new Email system: It is recommended to use Dovecot, as this is very stable, fast, feature rich and easy to scale<br />
<br />
<br />
{{OX_HE_Tutorial_Dovecot}}<br />
<br />
<br />
{{AppSuite:OX_Tutorial_Next}}</div>Martin.schneider