|
|
| (852 intermediate revisions by 35 users not shown) |
| Line 1: |
Line 1: |
| == Introduction ==
| | {{Version_until|7.8.2}} |
|
| |
|
| 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.
| | '''The latest content on this page has moved to https://documentation.open-xchange.com/components/middleware/http/latest/index.html.''' |
|
| |
|
| === Low level protocol ===
| | 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. |
| | |
| The client accesses the server though HTTP GET, POST and PUT requests. 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>.
| |
| | |
| 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:
| |
| | |
| Value ::= "null" | Boolean | Number | String | Array | Object
| |
| Boolean ::= "true" | "false"
| |
| Number ::= see NumericLiteral in ECMA 262 3rd edition
| |
| String ::= \"([^"\n\\]|\\["\n\\])*\"
| |
| Array ::= "[]" | "[" Value ("," Value)* "]"
| |
| Object ::= "{}" | "{" Name ":" Value ("," Name ":" Value)* "}"
| |
| Name ::= [A-Fa-f][0-9A-Fa-f_]*
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| {| id="ResponseBody" cellspacing="0" border="1"
| |
| |+ align="bottom" | Response body
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | data || Value || Payload of the response.
| |
| |-
| |
| | timestamp || Timestamp || Current timestamp on the server.
| |
| |-
| |
| | error || String || English error message. Present in case of errors.
| |
| |-
| |
| | error_params || Array || Replacement parameters for the error message.
| |
| |-
| |
| | error_id || String || Unique error identifier to help finding this error instance in the server logs.
| |
| |-
| |
| | code || String || Error code consisting of a three-letter category and a four-digit message number, separated by a dash.
| |
| |-
| |
| | category || Number || Category to which the error message belongs:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || An error resulting from wrong or missing input from front-end (e.g. mandatory field missing).
| |
| |-
| |
| | 2 || An error strictly related to user configuration which denies requested operation.
| |
| |-
| |
| | 3 || An error related to insufficient permission settings.
| |
| |-
| |
| | 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).
| |
| |-
| |
| | 5 || A subsystem or third party service is down and therefore does not respond (e.g. database is down).
| |
| |-
| |
| | 6 || The underlying socket connection is corrupt, empty or closed. Only a temporary error that does not affect the whole system.
| |
| |-
| |
| | 7 || An internal java-related (runtime) exception.
| |
| |-
| |
| | 8 || A programming error which was caused by incorrect programm code.
| |
| |-
| |
| | 9 || A concurrent modification.
| |
| |-
| |
| | 10 || Error in system setup detected.
| |
| |-
| |
| | 11 || The requested operation could not be performed cause an underlying resource is full or busy (e.g. IMAP folder exceeds quota).
| |
| |-
| |
| | 12 || The given data could not be stored into the database because an attribute contains a too long value.
| |
| |}
| |
| |}
| |
| | |
| 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.
| |
| | |
| 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>.
| |
| | |
| === Error handling ===
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| A simplified conversion specification, as used for error messages, is either of the form %s or %''n''$s, where ''n'' is an array index for error_params as a decimal number. The conversion specifications are replaced from left to right by elements from error_params, starting at index 0. %s is replaced by the element with the current index and the index is incremented. %''n''$s is replaced by the element with index ''n'' and the index is set to ''n'' + 1.
| |
| | |
| === Date and time ===
| |
| | |
| 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.
| |
| | |
| 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)).
| |
| | |
| 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.
| |
| | |
| 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]].
| |
| | |
| {| id="DateAndTimeTypes" cellspacing="0" border="1"
| |
| |+ align="bottom" | Date and time types
| |
| ! Type !! Time !! Timezone !! Comment
| |
| |-
| |
| | Date || No || UTC || Date without time.
| |
| |-
| |
| | Time || Yes || User || Date and time.
| |
| |-
| |
| | Timestamp || Yes || UTC || Timestamp or unique sequence number.
| |
| |-
| |
| |}
| |
| | |
| === Updates ===
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| === Editing ===
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| 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.
| |
| | |
| === File uploads ===
| |
| | |
| 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”.
| |
| | |
| 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 of the form:
| |
| | |
| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" <nowiki>"http://www.w3.org/TR/html4/strict.dtd"</nowiki>>
| |
| <html>
| |
| <META http-equiv="Content-Type" content="text/html; charset=UTF-8">
| |
| <head>
| |
| <script type="text/javascript">
| |
| parent.callback_**action**(**json**);
| |
| </script>
| |
| </head>
| |
| </html>
| |
| | |
| 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. The content-type of the answer is <code>text/html</code>.
| |
| | |
| === Documentation conventions ===
| |
| | |
| 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:
| |
| * the HTTP method followed by the request URI, inclusing the URI parameter action, which is used to differentiate methods,
| |
| * a list of URI parameters which can or must be supplied by the client,
| |
| * for PUT requests, content of the request body,
| |
| * "Response with timestamp:"if the timestamp field is required in the response body or simply "Response:" if not,
| |
| * content of the response payload, unless it is supposed to be empty.
| |
| | |
| == Module "login" ==
| |
| | |
| The login module is used to obtain a session ID from the user's login credentials.
| |
| | |
| === Login ===
| |
| | |
| GET <code>/ajax/login?action=login</code>
| |
| | |
| Parameters:
| |
| * <code>name</code> – The login name.
| |
| * <code>password</code> – The password.
| |
| | |
| Response: A string containing the session ID used for all subsequent requests.
| |
| | |
| === Logout ===
| |
| | |
| GET <code>/ajax/login?action=logout</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| == Module "config" ==
| |
| | |
| 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.
| |
| | |
| The namespace looks like the following:
| |
| | |
| * <code>/ajax/config/</code>
| |
| ** <code>gui</code> – An string containing GUI-specific settings (currently, it is a huge [[#Low_level_protocol | JSON]] object).
| |
| ** <code>identifier</code> – the unique identifier of the user (read-only).
| |
| ** <code>contact_id</code> – the unique identifier of the contact data of the user (read-only).
| |
| ** <code>language</code> – the configured language of the user.
| |
| ** <code>timezone</code> – the configured timezone of the user.
| |
| ** <code>calendarnotification</code> - send a mail notification for appointments
| |
| ** <code>tasknotification</code> - send a mail notification for tasks
| |
| ** <code>folder/</code> – the standard folder of the user
| |
| *** <code>tasks</code> – the standard task folder (read-only)
| |
| *** <code>calendar</code> – the standard calendar folder (read-only)
| |
| *** <code>contacts</code> – the standard contacts folder (read-only)
| |
| *** <code>infostore</code> – the private infostore folder (read-only)
| |
| ** <code>mail/</code> – settings for the email module
| |
| *** <code>folder/</code> – the standard email folders (read-only)
| |
| **** <code>inbox</code> – identifier of the folder that gets all incoming mails (read-only)
| |
| **** <code>drafts</code> – identifier of the folder with the mail drafts (read-only)
| |
| **** <code>trash</code> – identifier of the folder with the deleted mails (read-only)
| |
| **** <code>spam</code> – identifier of the folder with the spam mails (read-only)
| |
| **** <code>sent</code> – identifier of the folder with the sent mails (read-only)
| |
| *** <code>htmlinline</code> – activate inlining of HTML attachments.
| |
| *** <code>colorquote</code> – color quoted lines.
| |
| *** <code>emoticons</code> – display emoticons as graphics.
| |
| *** <code>harddelete</code> – delete emails at once.
| |
| *** <code>inlineforward</code> – forward messages as inline or attachment.
| |
| *** <code>vcard</code> – attach vcard when sending mails.
| |
| *** <code>notifyonreadack</code> – notify on read acknowledgement.
| |
| *** <code>msgpreview</code> – show a message preview.
| |
| *** <code>ignorereplytext</code>
| |
| *** <code>nocopytosent</code> – don't put a copy to the sent folder when sending mails.
| |
| | |
| === Get configuration data ===
| |
| | |
| GET <code>/ajax/config/path</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Response: Value of the node specified by path.
| |
| | |
| === Set configuration data ===
| |
| | |
| PUT <code>/ajax/config/path</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: The new value of the node specified by path.
| |
| | |
| == Module "folders" ==
| |
| | |
| The folders module is used to access the OX folder structure.
| |
| | |
| === Get root folders ===
| |
| | |
| GET <code>/ajax/folders?action=root</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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 [[#CommonObjectData | Common object data]] and [[#DetailedFolderData | Detailed folder data]]. The fields categories and private_flag are not available for folders.
| |
| | |
| 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.
| |
| | |
| {| id="CommonObjectData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Common object data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 1 || id || String || Object ID
| |
| |-
| |
| | 2 || created_by || String || User ID of the user who created this object.
| |
| |-
| |
| | 3 || modified_by || String || User ID of the user who last modified this object.
| |
| |-
| |
| | 4 || creation_date || Time || Date and time of creation.
| |
| |-
| |
| | 5 || last_modified || Time || Date and time of the last modification.
| |
| |-
| |
| | 20 || folder_id || String || Object ID of the parent folder.
| |
| |-
| |
| | 100 || categories || Array || Each element is a string, naming a category. Order is preserved. Changing the order counts as modification of the object. Not present in folder objects.
| |
| |-
| |
| | 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.
| |
| |}
| |
| | |
| {| id="DetailedFolderData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Detailed folder data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 300 || title || String || Name of this folder.
| |
| |-
| |
| | 301 || module || String || Name of the module which implements this folder.
| |
| |-
| |
| | 302 || type || Number || Type of folder:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || private
| |
| |-
| |
| | 2 || public
| |
| |-
| |
| | 3 || shared
| |
| |-
| |
| | 5 || system folder
| |
| |}
| |
| |-
| |
| | 304 || subfolders || Boolean || true if this folder has subfolders.
| |
| |-
| |
| | 305 || own_rights || Number or String || Permissions which apply to the current user, as described either in [[#PermissionFlags | Permission flags]] or in RFC 2086.
| |
| |-
| |
| | || permissions || Array || Each element is an object described in [[#PermissionObject | Permission object]].
| |
| |-
| |
| | 307 || summary || String || Information about contained objects.
| |
| |-
| |
| | 308 || standard_folder || Boolean || Indicates whether or not folder is marked as a default folder (only OX folder)
| |
| |-
| |
| | 309 || total || Number || The number of objects in this Folder.
| |
| |-
| |
| | 310 || new || Number || The number of new objects in this Folder.
| |
| |-
| |
| | 311 || unread || Number || The number of unread objects in this Folder.
| |
| |-
| |
| | 312 || deleted || Number || The number of deleted objects in this Folder.
| |
| |}
| |
| | |
| {| id="PermissionFlags" cellspacing="0" border="1"
| |
| |+ align="bottom" | Permission flags
| |
| ! Bits !! Value
| |
| |-
| |
| | 0-61 || Folder permissions:
| |
| {| cellspacing="0" border="1"
| |
| | 0 || No permissions.
| |
| |-
| |
| | 1 || See the folder.
| |
| |-
| |
| | 2 || Create objects in the folder.
| |
| |-
| |
| | 4 || Create subfolders.
| |
| |-
| |
| | 64 || Admin.
| |
| |}
| |
| |-
| |
| | 7-13 || Read permissions for objects in the folder:
| |
| {| cellspacing="0" border="1"
| |
| | 0 || No permissions.
| |
| |-
| |
| | 1 || Read only own objects.
| |
| |-
| |
| | 2 || Read all objects.
| |
| |-
| |
| | 64 || Admin.
| |
| |}
| |
| |-
| |
| | 14-20 || Write permissions for objects in the folder:
| |
| {| cellspacing="0" border="1"
| |
| | 0 || No permissions.
| |
| |-
| |
| | 1 || Modify only own objects.
| |
| |-
| |
| | 2 || Modify all objects.
| |
| |-
| |
| | 64 || Admin.
| |
| |}
| |
| |-
| |
| | 21-27 || Delete permissions for objects in the folder:
| |
| {| cellspacing="0" border="1"
| |
| | 0 || No permissions.
| |
| |-
| |
| | 1 || Delete only own objects.
| |
| |-
| |
| | 2 || Delete all objects.
| |
| |-
| |
| | 64 || Admin.
| |
| |}
| |
| |-
| |
| | 28 || Admin flag:
| |
| {| cellspacing="0" border="1"
| |
| | 0 || No permissions.
| |
| |-
| |
| | 1 || Allowed to modify permissions.
| |
| |}
| |
| |}
| |
| | |
| {| id="PermissionObject" cellspacing="0" border="1"
| |
| |+ align="bottom" | Permission object
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | bits || Number || For non-mail folders, a number as described in [[#PermissionFlags | Permission flags]].
| |
| |-
| |
| | rights || String || For mail folders, the rights string as defined in RFC 2086.
| |
| |-
| |
| | entity || Number || User ID of the user or group to which this permission applies.
| |
| |-
| |
| | group || Boolean || true if entity refers to a group, false if it refers to a user.
| |
| |}
| |
| | |
| === Get subfolders ===
| |
| | |
| GET <code>/ajax/folders?action=list</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>parent</code> – Object ID of a folder, which is the parent folder of the requested folders.
| |
| * <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 [[#CommonObjectData | Common object data]] and [[#DetailedFolderData | Detailed folder data]]. The fields categories and private_flag are not available for folders.
| |
| | |
| 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.
| |
| | |
| === Get path ===
| |
| | |
| GET <code>/ajax/folders?action=path</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of a folder.
| |
| * <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 [[#CommonObjectData | Common object data]] and [[#DetailedFolderData | Detailed folder data]]. The fields categories and private_flag are not available for folders.
| |
| | |
| 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.
| |
| | |
| === Get updated folders ===
| |
| | |
| GET <code>/ajax/folders?action=updates</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>parent</code> – Object ID of a folder, which is the parent folder of the requested folders.
| |
| * <code>timestamp</code> – Timestamp of the last update of the requested folders.
| |
| * <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.
| |
| * <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 [[#CommonObjectData | Common object data]] and [[#DetailedFolderData | Detailed folder data]]. The fields categories and private_flag are not available for folders.
| |
| | |
| 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 are identified by their object IDs as plain strings, without being part of a nested array.
| |
| | |
| === Get a folder ===
| |
| | |
| GET <code>/ajax/folders?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested folder.
| |
| | |
| Response with timestamp: An object containing all data of the requested folder. The fields of the object are listed in [[#CommonObjectData | Common object data]] and [[#DetailedFolderData | Detailed folder data]]. The fields id, categories and private_flag are 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]].
| |
| | |
| === Update a folder ===
| |
| | |
| PUT <code>/ajax/folders?action=update</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the updated folder.
| |
| * <code>timestamp</code> – Timestamp of the updated folder. If the folder was modified after the specified timestamp, then the update must fail.
| |
| | |
| Request body: Folder object as described in [[#CommonObjectData | Common object data]] and [[#DetailedFolderData | Detailed folder data]]. Only modified fields are present.
| |
| | |
| === Create a folder ===
| |
| | |
| PUT <code>/ajax/folders?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: Folder object as described in [[#CommonObjectData | Common object data]] and [[#DetailedFolderData | Detailed folder data]]. The fields id, categories and private_flag are not present.
| |
| | |
| Response: Object ID of the newly created folder.
| |
| | |
| === Delete folders ===
| |
| | |
| PUT <code>/ajax/folders?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>timestamp</code> – Timestamp of the last update of the deleted folders.
| |
| | |
| Request body: An array with object IDs of the deleted folders.
| |
| | |
| Response: An array with object IDs of folders which were modified after the specified timestamp and were therefore not deleted.
| |
| | |
| == Module "tasks" ==
| |
| | |
| The tasks module is used to access task information.
| |
| | |
| === Get all tasks ===
| |
| | |
| GET <code>/ajax/tasks?action=all</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| | |
| 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.
| |
| | |
| {| id="DetailedTaskAndAppointmentData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Detailed task and appointment data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 200 || title || String || Short description.
| |
| |-
| |
| | 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.
| |
| |-
| |
| | 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.
| |
| |-
| |
| | 203 || note || String || Long description.
| |
| |-
| |
| | 204 || alarm || Number || Specifies when to notify the participantsas the number of minutes before the end of the task or before the start of the appointment.
| |
| |-
| |
| | 206 || recurrence_id || Number || Object ID of the entire appointment sequence. Present if and only if recurrence_type > 0.
| |
| |-
| |
| | 207 || recurrence_position || Number || 1-based position of an individual appointment in a sequence. Present if and only if recurrence_type > 0.
| |
| |-
| |
| | 208 || recurrence_date_position || Date || Date of an individual appointment in a sequence. Present if and only if recurrence_type > 0.
| |
| |-
| |
| | 209 || recurrence_type || Number || Specifies the type of the recurrence for a task sequence:
| |
| {| cellspacing="0" border="1"
| |
| | 0 || none (single event)
| |
| |-
| |
| | 1 || daily
| |
| |-
| |
| | 2 || weekly
| |
| |-
| |
| | 3 || monthly
| |
| |-
| |
| | 4 || yearly
| |
| |}
| |
| |-
| |
| | 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).
| |
| |-
| |
| | 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.
| |
| |-
| |
| | 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.
| |
| |-
| |
| | 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.
| |
| |-
| |
| | 216 || until || Date || Exclusive 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.
| |
| |-
| |
| | 217 || notification || Boolean || If true, all participants are notified of any changes to this object.
| |
| |-
| |
| | 220 || participants || Array || Each element identifies a participant, user group or booked resource as described in [[#participantIdentifier | Participant identifier]].
| |
| |-
| |
| | 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.
| |
| |}
| |
| | |
| {| id="ParticipantIdentifier" cellspacing="0" border="1"
| |
| |+ align="bottom" | Participant identifier
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || Number || User ID
| |
| |-
| |
| | type || Number || Type of participant:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || user
| |
| |-
| |
| | 2 || user group
| |
| |-
| |
| | 3 || resource
| |
| |-
| |
| | 4 || resource group
| |
| |}
| |
| |}
| |
| | |
| {| id="UserParticipantObject" cellspacing="0" border="1"
| |
| |+ align="bottom" | User participant object
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || Number || User ID
| |
| |-
| |
| | display_name || String || Displayable name of the participant.
| |
| |-
| |
| | confirmation || Number ||
| |
| {| cellspacing="0" border="1"
| |
| | 0 || none
| |
| |-
| |
| | 1 || accepted
| |
| |-
| |
| | 2 || declined
| |
| |-
| |
| | 3 || tentative
| |
| |}
| |
| |-
| |
| | confirmmessage || String || Confirm Message of the participant
| |
| |}
| |
| | |
| {| id="DetailedTaskData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Detailed task data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 300 || status || Number || Status of the task:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || not started
| |
| |-
| |
| | 2 || in progress
| |
| |-
| |
| | 3 || done
| |
| |-
| |
| | 4 || waiting
| |
| |-
| |
| | 5 || deferred
| |
| |}
| |
| |-
| |
| | 301 || percent_completed || Number || How much of the task is completed. An integer number between 0 and 100.
| |
| |-
| |
| | 302 || actual_costs
| |
| |-
| |
| | 303 || actual_duration
| |
| |-
| |
| | 304 || after_complete
| |
| |-
| |
| | 305 || billing_information
| |
| |-
| |
| | 306 || project_id
| |
| |-
| |
| | 307 || target_costs
| |
| |-
| |
| | 308 || target_duration
| |
| |-
| |
| | 309 || priority
| |
| |-
| |
| | 310 || duration_type
| |
| |-
| |
| | 311 || type_of_costs
| |
| |-
| |
| | 312 || currency
| |
| |-
| |
| | 313 || trip_meter
| |
| |-
| |
| | 314 || companies
| |
| |-
| |
| | 315 || date_completed
| |
| |-
| |
| | 102 || color_label
| |
| |}
| |
| | |
| === Get a list of tasks ===
| |
| | |
| PUT <code>/ajax/tasks?action=list</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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]].
| |
| | |
| Request body: An array of with object IDs of requested tasks.
| |
| | |
| 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.
| |
| | |
| === Get updated tasks ===
| |
| | |
| GET <code>/ajax/tasks?action=updates</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| * <code>timestamp</code> – Timestamp of the last update of the requested tasks.
| |
| ignore (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.
| |
| | |
| 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 are identified by their object IDs as plain strings, without being part of a nested array.
| |
| | |
| === Get a task ===
| |
| | |
| GET <code>/ajax/tasks?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested task.
| |
| | |
| 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.
| |
| | |
| === Update a task ===
| |
| | |
| PUT <code>/ajax/tasks?action=update</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the updated task.
| |
| * <code>timestamp</code> – Timestamp of the updated task. If the task was modified after the specified timestamp, then the update must fail.
| |
| | |
| 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.
| |
| | |
| === Create a task ===
| |
| | |
| PUT <code>/ajax/tasks?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| 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.
| |
| | |
| Response: Object ID of the newly created task.
| |
| | |
| === Delete tasks ===
| |
| | |
| PUT <code>/ajax/tasks?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>timestamp</code> – Timestamp of the last update of the deleted tasks.
| |
| | |
| Request body: An object in the field “id” and “folder_id”.
| |
| | |
| Response: An array with object IDs of tasks which were modified after the specified timestamp and were therefore not deleted.
| |
| | |
| === Confirm task ===
| |
| | |
| PUT <code>/ajax/tasks?action=confirm</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the to confirm task.
| |
| * <code>folder</code> – ID of the folder through that the task is accessed.
| |
| * <code>timestamp</code> – Timestamp of the last update of the to confirm task.
| |
| | |
| Request body: An object with the fields "confirmation" and "confirmmessage" as described in [[#UserParticipantObject | User participant object]].
| |
| | |
| Response: Nothing, except the standard response object with empty data, the timestamp of the confirmed and thereby updated task, and maybe errors.
| |
| | |
| == Module "contacts" ==
| |
| | |
| The contacts module is used to access contact information.
| |
| | |
| === Get all contacts ===
| |
| | |
| GET <code>/ajax/contacts?action=all</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| | |
| 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.
| |
| | |
| {| id="DetailedContactData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Detailed contact data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 500 || display_name || String
| |
| |-
| |
| | 501 || first_name || String || First name.
| |
| |-
| |
| | 502 || last_name || String || Last name.
| |
| |-
| |
| | 503 || second_name || String
| |
| |-
| |
| | 504 || suffix || String
| |
| |-
| |
| | 505 || title || String
| |
| |-
| |
| | 506 || street_home || String
| |
| |-
| |
| | 507 || postal_code_home
| |
| |-
| |
| | 508 || city_home || String
| |
| |-
| |
| | 509 || state_home || String
| |
| |-
| |
| | 510 || country_home || String
| |
| |-
| |
| | 511 || birthday || Date
| |
| |-
| |
| | 512 || marital_status
| |
| |-
| |
| | 513 || number_of_children
| |
| |-
| |
| | 514 || profession || String
| |
| |-
| |
| | 515 || nickname || String
| |
| |-
| |
| | 516 || spouse_name || String
| |
| |-
| |
| | 517 || anniversary || Date
| |
| |-
| |
| | 518 || note || String
| |
| |-
| |
| | 519 || department || String
| |
| |-
| |
| | 520 || position || String
| |
| |-
| |
| | 521 || employee_type
| |
| |-
| |
| | 522 || room_number
| |
| |-
| |
| | 523 || street_business || String
| |
| |-
| |
| | 525 || postal_code_business
| |
| |-
| |
| | 526 || city_business || String
| |
| |-
| |
| | 527 || state_business || String
| |
| |-
| |
| | 528 || country_business || String
| |
| |-
| |
| | 529 || number_of_employees
| |
| |-
| |
| | 530 || sales_volume
| |
| |-
| |
| | 531 || tax_id || String
| |
| |-
| |
| | 532 || commercial_register || String
| |
| |-
| |
| | 533 || branches || String
| |
| |-
| |
| | 534 || business_category || String
| |
| |-
| |
| | 535 || info || String
| |
| |-
| |
| | 536 || manager_name || String
| |
| |-
| |
| | 537 || assistant_name || String
| |
| |-
| |
| | 538 || street_other || String
| |
| |-
| |
| | 539 || city_other || String
| |
| |-
| |
| | 540 || postal_code_other
| |
| |-
| |
| | 541 || country_other || String
| |
| |-
| |
| | 542 || telephone_business1 || String
| |
| |-
| |
| | 543 || telephone_business2 || String
| |
| |-
| |
| | 544 || fax_business || String
| |
| |-
| |
| | 545 || telephone_callback || String
| |
| |-
| |
| | 546 || telephone_car || String
| |
| |-
| |
| | 547 || telephone_company || String
| |
| |-
| |
| | 548 || telephone_home1 || String
| |
| |-
| |
| | 549 || telephone_home2 || String
| |
| |-
| |
| | 550 || fax_home || String
| |
| |-
| |
| | 551 || cellular_telephone1 || String
| |
| |-
| |
| | 552 || cellular_telephone2 || String
| |
| |-
| |
| | 553 || telephone_other || String
| |
| |-
| |
| | 554 || fax_other || String
| |
| |-
| |
| | 555 || email1 || String
| |
| |-
| |
| | 556 || email2 || String
| |
| |-
| |
| | 557 || email3 || String
| |
| |-
| |
| | 558 || url || String
| |
| |-
| |
| | 559 || telephone_isdn || String
| |
| |-
| |
| | 560 || telephone_pager || String
| |
| |-
| |
| | 561 || telephone_primary || String
| |
| |-
| |
| | 562 || telephone_radio || String
| |
| |-
| |
| | 563 || telephone_telex || String
| |
| |-
| |
| | 564 || telephone_ttytdd || String
| |
| |-
| |
| | 565 || instant_messenger1 || String
| |
| |-
| |
| | 566 || instant_messenger2 || String
| |
| |-
| |
| | 567 || telephone_ip || String
| |
| |-
| |
| | 568 || telephone_assistant || String
| |
| |-
| |
| | 569 || company || String
| |
| |-
| |
| | 570 || image1
| |
| |-
| |
| | 571 || userfield01
| |
| |-
| |
| | 572 || userfield02
| |
| |-
| |
| | 573 || userfield03
| |
| |-
| |
| | 574 || userfield04
| |
| |-
| |
| | 575 || userfield05
| |
| |-
| |
| | 576 || userfield06
| |
| |-
| |
| | 577 || userfield07
| |
| |-
| |
| | 578 || userfield08
| |
| |-
| |
| | 579 || userfield09
| |
| |-
| |
| | 580 || userfield10
| |
| |-
| |
| | 581 || userfield11
| |
| |-
| |
| | 582 || userfield12
| |
| |-
| |
| | 583 || userfield13
| |
| |-
| |
| | 584 || userfield14
| |
| |-
| |
| | 585 || userfield15
| |
| |-
| |
| | 586 || userfield16
| |
| |-
| |
| | 587 || userfield17
| |
| |-
| |
| | 588 || userfield18
| |
| |-
| |
| | 589 || userfield19
| |
| |-
| |
| | 590 || userfield20
| |
| |-
| |
| | 591 || links || Array || An array of objects containing links to other contacts. Each contact is describes by an object as defined in [[#ContactLinkData | Contact link data]].
| |
| |-
| |
| | 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]].
| |
| |-
| |
| | 593 || context_id
| |
| |-
| |
| | 594 || number_of_distributuion_list
| |
| |-
| |
| | 595 || number_of_links
| |
| |-
| |
| | 596 || contains_image1
| |
| |-
| |
| | 597 || image_last_modified
| |
| |-
| |
| | 598 || state_other
| |
| |-
| |
| | 599 || file_as
| |
| |-
| |
| | 600 || attachment
| |
| |-
| |
| | 601 || image1_content_type
| |
| |-
| |
| | 602 || mark_as_distributionlist
| |
| |-
| |
| | 605 || default_address
| |
| |-
| |
| | 102 || color_label
| |
| |-
| |
| | 524 || internal_userid
| |
| | |
| |}
| |
| | |
| {| id="ContactLinkData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Contact link data
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || String || Object ID
| |
| |-
| |
| | first_name || String || First name
| |
| |-
| |
| | last_name || String || Last name
| |
| |}
| |
| | |
| {| id="DistributionListMember" cellspacing="0" border="1"
| |
| |+ align="bottom" | Distribution list member
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || String || User ID of the member if the member is an existing contact.
| |
| |-
| |
| | first_name || String || First name
| |
| |-
| |
| | last_name || String || Last name
| |
| |-
| |
| | mail || String || Email address
| |
| |-
| |
| | mail_field || Number || Which email field of an existing contact (if any) is used for the mail field.
| |
| {| cellspacing="0" border="1"
| |
| | 0 || independent contact
| |
| |-
| |
| | 1 || default email field (email1)
| |
| |-
| |
| | 2 || second email field (email2)
| |
| |-
| |
| | 3 || third email field (email3)
| |
| |}
| |
| |}
| |
| | |
| === Get a list of contacts ===
| |
| | |
| PUT <code>/ajax/contacts?action=list</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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]].
| |
| | |
| Request body: An array with object IDs of requested contacts.
| |
| | |
| 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.
| |
| | |
| === Get updated contacts ===
| |
| | |
| GET <code>/ajax/contacts?action=updates</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| * <code>timestamp</code> – Timestamp of the last update of the requested contacts.
| |
| * <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.
| |
| | |
| 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 are identified by their object IDs as plain strings, without being part of a nested array.
| |
| | |
| === Get a contact ===
| |
| | |
| GET <code>/ajax/contacts?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested contact.
| |
| | |
| 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.
| |
| | |
| === Update a contact ===
| |
| | |
| PUT <code>/ajax/contacts?action=update</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the updated contact.
| |
| * <code>timestamp</code> – Timestamp of the updated contact. If the contact was modified after the specified timestamp, then the update must fail.
| |
| | |
| Request body: Contact object as described in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]]. Only modified fields are present.
| |
| | |
| === Create a contact ===
| |
| | |
| PUT <code>/ajax/contacts?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: Contact object as described in [[#CommonObjectData | Common object data]] and [[#DetailedContactData | Detailed contact data]]. The field id is not included.
| |
| | |
| Response: Object ID of the newly created contact.
| |
| | |
| === Delete contacts ===
| |
| | |
| POST <code>/ajax/contacts?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>timestamp</code> – Timestamp of the last update of the deleted contacts.
| |
| | |
| Request body: An object with the fields “id” and “folder_id”.
| |
| | |
| Response: An array with object IDs of contacts which were modified after the specified timestamp and were therefore not deleted.
| |
| | |
| === Search contacts ===
| |
| | |
| PUT <code>/ajax/contacts?action=search</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>columns</code> – The requested fields
| |
| | |
| Request body: An Object as described in [[#SearchContacts | Search contacts]].
| |
| | |
| {| id="SearchContacts" cellspacing="0" border="1"
| |
| |+ align="bottom" | Search contacts
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | 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.
| |
| |}
| |
| | |
| 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.
| |
| | |
| == Module "calendar" ==
| |
| | |
| The calendar module is used to access calendar data.
| |
| | |
| === Get all appointments ===
| |
| | |
| GET <code>/ajax/calendar?action=all</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> (optional) – Object ID of the folder, whose contents are queried. If not specified, defaults to all calendar folders.
| |
| * <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]].
| |
| * <code>start</code> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.
| |
| * <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.
| |
| | |
| 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.
| |
| | |
| {| id="DetailedAppointmentData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Detailed appointment data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 400 || location || String || Location
| |
| |-
| |
| | 401 || full_time || Boolean || True if the appointment is a whole day appointment, false otherwise.
| |
| |-
| |
| | 402 || shown_as || Number || Describes, how this appointment appears in availability queries:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || reserved
| |
| |-
| |
| | 2 || temporary
| |
| |-
| |
| | 3 || absent
| |
| |-
| |
| | 4 || free
| |
| |}
| |
| |-
| |
| | 102 || color_label || Number || Color number used by Outlook to label the appointment. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers. TODO: zero allowed?
| |
| |}
| |
| | |
| === Get appointment information ===
| |
| | |
| GET <code>/ajax/calendar?action=has</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>start</code> – Lower inclusive limit of the queried range as a Date. Only appointments which end on or after this date are returned.
| |
| * <code>end</code> – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.
| |
| | |
| Response is an array of booleans. Array length is the number of days.
| |
| | |
| === Get a list of appointments ===
| |
| | |
| PUT <code>/ajax/calendar?action=list</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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]].
| |
| | |
| Request body: An array of requested appointments. Each element identifies one appointment and is described in [[#FullIdentifierForAnAppointment | Full identifier for an appointment]].
| |
| | |
| 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.
| |
| | |
| {| id="FullIdentifierForAnAppointment" cellspacing="0" border="1"
| |
| |+ align="bottom" | Full identifier for an appointment
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || String || Object ID
| |
| |-
| |
| | pos || Number || Value of the field recurrence_position, if present in the appointment.
| |
| |}
| |
| | |
| === Get updated appointments ===
| |
| | |
| GET <code>/ajax/calendar?action=updates</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <code>timestamp</code> – Timestamp of the last update of the requested appointments.
| |
| * <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.
| |
| * <code>end</code> (optional) – Upper exclusive limit of the queried range as a Date. Only appointments which start before this date are returned.
| |
| * <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.
| |
| | |
| 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 are 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.
| |
| | |
| === Get an appointment ===
| |
| | |
| GET <code>/ajax/calendar?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested appointment.
| |
| | |
| 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.
| |
| | |
| === Update an appointment ===
| |
| | |
| PUT <code>/ajax/calendar?action=update</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the updated appointment.
| |
| * <code>timestamp</code> – Timestamp of the updated appointment. If the appointment was modified after the specified timestamp, then the update must fail.
| |
| | |
| 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.
| |
| | |
| === Create an appointment ===
| |
| PUT <code>/ajax/calendar?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| 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.
| |
| | |
| Response: Object ID of the newly created appointment.
| |
| | |
| === Delete appointments ===
| |
| | |
| POST <code>/ajax/calendar?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>timestamp</code> – Timestamp of the last update of the deleted appointments.
| |
| | |
| Request body: The appointment object to delete. The fields for the object are described in [[#FullIdentifierForAnAppointment | Full identifier for an appointment]].
| |
| | |
| 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]].
| |
| | |
| == Module "mail" ==
| |
| | |
| The mail module is used to access mail data.
| |
| | |
| 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".
| |
| | |
| === Get all mails ===
| |
| | |
| GET <code>/ajax/mail?action=all</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <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.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| * TODO: Search.
| |
| | |
| 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.
| |
| | |
| {| id="DetailedMailData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Detailed mail data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 600 || id || String || Object ID
| |
| |-
| |
| | 601 || folder_id || String || Object ID of the parent folder
| |
| |-
| |
| | 602 || attachment || Boolean || Specifies whether this mail has attachments.
| |
| |-
| |
| | 603 || from || Array || Each element is a string specifying one sender.
| |
| |-
| |
| | 604 || to || Array || Each element is a string specifying one receiver.
| |
| |-
| |
| | 605 || cc || Array || Each element is a string specifying one carbon-copy receiver.
| |
| |-
| |
| | 606 || bcc || Array || Each element is a string specifying one blind carbon-copy receiver.
| |
| |-
| |
| | 607 || subject || String || Subject line.
| |
| |-
| |
| | 608 || size || Number || Size of the mail in bytes.
| |
| |-
| |
| | 609 || sent_date || Time || Date and time as specified in the mail by the sending client.
| |
| |-
| |
| | 610 || received_date || Time || Date and time as measured by the receiving server.
| |
| |-
| |
| | 611 || flags || Number || Various system flags. A sum of zero or more of following values:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || answered
| |
| |-
| |
| | 2 || deleted
| |
| |-
| |
| | 4 || draft
| |
| |-
| |
| | 8 || flagged
| |
| |-
| |
| | 16 || recent
| |
| |-
| |
| | 32 || seen
| |
| |-
| |
| | 64 || user
| |
| |}
| |
| See javax.mail.Flags.Flag for details.
| |
| |-
| |
| | 612 || level || Number || Zero-based nesting level in a thread.
| |
| |-
| |
| | 613 || disp_notification_to || String || Content of message's header “Disposition-Notification-To”
| |
| |-
| |
| | 614 || priority || Number || Value of message's “X-Priority” header
| |
| |-
| |
| | || user || 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.
| |
| |-
| |
| | || 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.
| |
| |-
| |
| | || nested_msgs || Array || Each element is a mail object as described in this table, except for fields id, folder_id and attachment.
| |
| |}
| |
| | |
| {| id="Attachment" cellspacing="0" border="1"
| |
| |+ align="bottom" | Attachment
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || String || Object ID (unique only inside the same message)
| |
| |-
| |
| | content_type || String || MIME type
| |
| |-
| |
| | content || String || Content as text. Present only if easily convertible to text.
| |
| |-
| |
| | filename || String || Displayed filename (mutually exclusive with content).
| |
| |-
| |
| | size || Number || Size of the attachment in bytes.
| |
| |-
| |
| | disp || String || Attachment's disposition: null, inline, attachment or alternative.
| |
| |}
| |
| | |
| === Get a list of mails ===
| |
| | |
| PUT <code>/ajax/mail?action=list</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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]].
| |
| | |
| Request body: An array with object IDs of requested mails.
| |
| | |
| 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.
| |
| | |
| === Not IMAP: Get updated mails ===
| |
| | |
| GET <code>/ajax/mail?action=updates</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose mails are queried.
| |
| * <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]].
| |
| * <code>timestamp</code> – Timestamp of the last update of the requested mails.
| |
| * <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.
| |
| | |
| Response with timestamp: An array with new, modified and deleted mails. New and modified mails are represented by arrays. The elements of each array contain the information specified by the corresponding identifiers in the columns parameter. Deleted mails are identified by their object IDs as plain strings, without being part of a nested array.
| |
| | |
| === Get a mail ===
| |
| | |
| GET <code>/ajax/mail?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested mail.
| |
| | |
| 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.
| |
| | |
| === Get a mail attachment ===
| |
| | |
| GET <code>/ajax/mail?action=attachment</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the mail which contains the attachment.
| |
| * <code>attachment</code> – ID of the requested attachment
| |
| * <code>save</code> – 1 overwrites the defined mimetype for this attachment to force the download dialog, otherwise 0.
| |
| | |
| 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.
| |
| | |
| === Append to a mail ===
| |
| | |
| POST <code>/ajax/mail?action=append</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the appended mail.
| |
| * Not IMAP: <code>timestamp</code> – Timestamp of the updated contact. If the contact was modified after the specified timestamp, then the update must fail.
| |
| * <code>mail</code> – Textual representation of a mail object as described in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included. The object is encoded as text/javascript like the request body for PUT requests.
| |
| * <code>attachment</code>''n'' (optional) – One or more attachments. n is a decimal integer starting with 0 and incrementing for every new attachment.
| |
| | |
| This method uses the encoding multipart/form-data or multipart/mixed.
| |
| | |
| === Create a mail ===
| |
| | |
| POST <code>/ajax/mail?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>mail</code> – Textual representation of a mail object as described in [[#DetailedMailData | Detailed mail data]]. The fields id and attachment are not included. The object is encoded as text/javascript like the request body for PUT requests.
| |
| * <code>attachment</code>''n'' (optional) – One or more attachments. n is a decimal integer starting with 0 and incrementing for every new attachment.
| |
| * <code>infostore_ids</code> (optional) – A comma-seperated list of infostore document IDs that ought to be attached to the mail
| |
| | |
| Not IMAP: Response: Object ID of the newly created mail.
| |
| | |
| This method uses the encoding multipart/form-data or multipart/mixed.
| |
| | |
| === Reply/Forward a mail ===
| |
| | |
| GET <code>/ajax/mail?action=reply</code>
| |
| GET <code>/ajax/mail?action=replyall</code>
| |
| GET <code>/ajax/mail?action=forward</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested Message.
| |
| * <code>folder</code> - Object ID of the folder, whose contents are queried.
| |
| | |
| 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.
| |
| | |
| === Delete mails ===
| |
| | |
| PUT <code>/ajax/mail?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * Not IMAP: <code>timestamp</code> – Timestamp of the last update of the deleted mails.
| |
| | |
| Request body: An array with object IDs of the deleted mails.
| |
| | |
| Not IMAP: Response: An array with object IDs of mails which were modified after the specified timestamp and were therefore not deleted.
| |
| | |
| == Module "groups" ==
| |
| | |
| The group module allows to query available groups. It is mainly used by the dialog for the selection of participants.
| |
| | |
| === Get a group ===
| |
| | |
| GET <code>/ajax/group?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – The group id.
| |
| | |
| Response: An array of group objects as described in [[#GroupResponse | Group response]].
| |
| | |
| === Search for participants ===
| |
| | |
| PUT <code>/ajax/group?action=search</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: An object with search parameters as described in [[#ParticipantSearch | Participant search]].
| |
| | |
| {| id="ParticipantSearch" cellspacing="0" border="1"
| |
| |+ align="bottom" | Participant search
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | 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.
| |
| |}
| |
| | |
| Response: An array of group objects as described in [[#GroupResponse | Group response]].
| |
| | |
| {| id="GroupResponse" cellspacing="0" border="1"
| |
| |+ align="bottom" | Group response
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || Number || ID
| |
| |-
| |
| | display_name || String || Display name
| |
| |-
| |
| | member || Array || Array of group member id's
| |
| |}
| |
| | |
| == Module "resource" ==
| |
| | |
| The resource module allows to query available resources. It is mainly used by the dialog for the selection of participants.
| |
| | |
| === Get a resource ===
| |
| | |
| GET <code>/ajax/resource?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – The resource id.
| |
| | |
| Response: An array of resource objects as described in [[#ResourceResponse | Resource response]].
| |
| | |
| === Search for resources ===
| |
| | |
| PUT <code>/ajax/resource?action=search</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: An object with search parameters as described in [[#ParticipantSearch | Participant search]].
| |
| | |
| {| id="ParticipantSearch" cellspacing="0" border="1"
| |
| |+ align="bottom" | Participant search
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | 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.
| |
| |}
| |
| | |
| Response: An array of resource objects as described in [[#ResourceResponse | Resource response]].
| |
| | |
| {| id="ResourceResponse" cellspacing="0" border="1"
| |
| |+ align="bottom" | Resource Response
| |
| ! Name !! Type !! Value
| |
| |-
| |
| | id || Number || ID
| |
| |-
| |
| | display_name || String || Display name
| |
| |}
| |
| | |
| == Module "infostore" ==
| |
| | |
| The infostore module combines the knowledge database, bookmarks and documents.
| |
| | |
| === Get all infoitems ===
| |
| | |
| GET <code>/ajax/infostore?action=all</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| | |
| 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.
| |
| | |
| {| id="DetailedInfoitemData" cellspacing="0" border="1"
| |
| |+ align="bottom" | Detailed infoitem data
| |
| ! ID !! Name !! Type !! Value
| |
| |-
| |
| | 700 || title || String || Title
| |
| |-
| |
| | 701 || url || String || Link/URL
| |
| |-
| |
| | 702 || filename || String || Displayed filename of the document.
| |
| |-
| |
| | 703 || file_mimetype || String || MIME type of the document. The client converts known types to more readable names before displaying them.
| |
| |-
| |
| | 704 || file_size || Number || Size of the document in bytes.
| |
| |-
| |
| | 705 || version || Number || Version number of the document. New documents start at 1. Every update increments the version by 1.
| |
| |-
| |
| | 706 || description || String || Description
| |
| |-
| |
| | 707 || locked_until || Time || The time until which this item will presumably be locked. Only set if the docment is currently locked, 0 otherwise.
| |
| |-
| |
| | 708 || file_md5sum || String || MD5Sum of the document.
| |
| |-
| |
| | 709 || version_comment || String || A version comment is used to file a changelog for the file.
| |
| |-
| |
| | 710 || current_version || Boolean || “true” if this version is the current version “false” otherwise.
| |
| |-
| |
| | 102 || color_label || Number || Color number used by Outlook to label the appointment. The assignment of colors to numbers is arbitrary and specified by the client. The numbers are integer numbers. TODO: zero allowed?
| |
| |}
| |
| | |
| === Get a list of infoitems ===
| |
| | |
| PUT <code>/ajax/infostore?action=list</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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]].
| |
| | |
| Request body: An array with object IDs of requested infoitems.
| |
| | |
| 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.
| |
| | |
| === Get updated infoitems ===
| |
| | |
| GET <code>/ajax/infostore?action=updates</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| * <code>timestamp</code> – Timestamp of the last update of the requested infoitems.
| |
| * <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.
| |
| | |
| 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 are identified by their object IDs as plain strings, without being part of a nested array.
| |
| | |
| === Get an infoitem ===
| |
| | |
| GET <code>/ajax/infostore?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested infoitem.
| |
| * <code>version</code> (optional) – If present the infoitem data describes the given version. Otherwise the current version is returned
| |
| | |
| 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.
| |
| | |
| === Search infoitems ===
| |
| | |
| PUT <code>/ajax/infostore?action=search</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>columns</code> – The requested fields as per tables [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| * <code>start</code> (optional) – The start index (inclusive) in the ordered search, that is requested.
| |
| * <code>end</code> (optional) – The last index (inclusive) from the ordered search, that is requested.
| |
| | |
| Request body: An Object as described in [[#SearchContacts | Search contacts]].
| |
| | |
| === Get an infoitem document ===
| |
| | |
| GET <code>/ajax/infostore/[filename]?action=document</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the requested infoitem.
| |
| * <code>version</code> (optional) – If present the infoitem data describes the given version. Otherwise the current version is returned
| |
| * <code>content_type</code>(optional) – If present the response declares the given content_type in the Content-Type header.
| |
| | |
| Response body: Rhe 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.
| |
| | |
| Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.
| |
| | |
| === Get all versions ===
| |
| | |
| GET <code>/ajax/infostore?action=versions</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the infoitem whose versions are requested.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| | |
| 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.
| |
| | |
| === Update an infoitem via PUT ===
| |
| | |
| PUT <code>/ajax/infostore?action=update</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <ciode>id</code> – Object ID of the updated infoitem.
| |
| * <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
| |
| | |
| Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.
| |
| | |
| === Update an infoitem via POST ===
| |
| | |
| POST <code>/ajax/infostore?action=update</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the updated infoitem.
| |
| * <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
| |
| * <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.
| |
| * <code>file</code> – File Metadata as per <input type=”file” />
| |
| | |
| Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.
| |
| | |
| Response: The response is sent as a HTML document (see introduction).
| |
| | |
| === Create an infoitem via PUT ===
| |
| | |
| PUT <code>/ajax/infostore?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included.
| |
| | |
| Response: Object ID of the newly created infoitem.
| |
| | |
| === Create an infoitem via POST ===
| |
| | |
| POST <code>/ajax/infostore?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. The field id is not included.
| |
| * <code>file</code> – File metadata as per <input type=”file” />
| |
| | |
| Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.
| |
| | |
| Response: Object ID of the newly created infoitem. The response is sent as a HTML document (see introduction).
| |
| | |
| === Save an attachment in the infostore ===
| |
| | |
| PUT <code>/ajax/infostore?action=saveAs</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>attached</code> – The Object ID of the Object with the attachment
| |
| * <code>folder</code> – The Folder ID of the Object with the attachment
| |
| * <code>module</code> – The Module type of the Object with the attachment.
| |
| * <code>Attachment</code> – The id of the attachement to save.
| |
| | |
| 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.
| |
| | |
| Response: Object ID of the newly created infoitem.
| |
| | |
| === Delete infoitems ===
| |
| | |
| POST <code>/ajax/infostore?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>timestamp</code> – Timestamp of the last update of the deleted infoitems.
| |
| | |
| Request body: An array with object IDs of the deleted infoitems.
| |
| | |
| Response: An array with object IDs of infoitems which were modified after the specified timestamp and were therefore not deleted.
| |
| | |
| === Delete versions of infostore documents ===
| |
| | |
| PUT <code>/ajax/infostore?action=detach</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – The ID of the base Object
| |
| * <code>folder</code> – The Folder of the Object
| |
| * <code>timestamp</code> - Timestamp of the infostore object
| |
| | |
| Request body: A List of arrays with the version numbers of the infoitems to detach.
| |
| | |
| Response: An array with version numbers that were not deleted.
| |
| | |
| Note: When the current version of a document is deleted the new current version will be the newest version.
| |
| | |
| === Delete all versions of infostore documents ===
| |
| | |
| PUT <code>/ajax/infostore?action=revert</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – The ID of the base Object
| |
| * <code>folder</code> – The Folder of the Object
| |
| * <code>timestamp</code> - Timestamp of the infostore object
| |
| | |
| Removes all versions of the infostore document leaving only the base object.
| |
| | |
| === Copy an infostore document via PUT ===
| |
| | |
| PUT <code>/ajax/infostore?action=copy</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – The ID of the base Object
| |
| * <code>folder</code> – The Folder of the Object
| |
| * <code>timestamp</code> - Timestamp of the infostore object
| |
| | |
| Request body: Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.
| |
| | |
| Response: The id of the newly created object
| |
| | |
| Note: Only the fields (and the file) of the current document will be copied. Those fields present in the request are modified accordingly.
| |
| | |
| === Copy an infostore document via POST ===
| |
| | |
| POST <code>/ajax/infostore?action=copy</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the updated infoitem.
| |
| * <code>timestamp</code> – Timestamp of the updated infoitem. If the infoitem was modified after the specified timestamp, then the update must fail.
| |
| * <code>json</code> - Infoitem object as described in [[#CommonObjectData | Common object data]] and [[#DetailedInfoitemData | Detailed infoitem data]]. Only modified fields are present.
| |
| * <code>file</code> – File Metadata as per <input type=”file” />
| |
| | |
| Request Body: Body of content-type “multipart/form-data” or “multipart/mixed” containing the above mentioned fields and file-data.
| |
| | |
| Response: The response is sent as a HTML document (see introduction).
| |
| | |
| Note: Only the fields (and the file) of the current document will be copied. Those fields present in the request are modified accordingly.
| |
| | |
| === Lock an infoitem ===
| |
| | |
| GET <code>/ajax/infostore?action=lock</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the infoitem that should be locked.
| |
| * <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.
| |
| | |
| Response with timestamp: Can only include errors.
| |
| | |
| === Unlock an infoitem ===
| |
| | |
| GET <code>/ajax/infostore?action=unlock</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – Object ID of the infoitem that should be unlocked.
| |
| | |
| Response with timestamp: Can only contain errors.
| |
| | |
| == Module "Links" ==
| |
| | |
| The link module provides the ability to connect two objects from any module.
| |
| | |
| === Get All Links from an Object ===
| |
| | |
| GET <code>/ajax/link?action=all</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – The Object ID of the Object
| |
| * <code>folder</code> – The Folder ID of the Object
| |
| * <code>module</code> – The Module type of the Object
| |
| | |
| Response: An Array with all Links ([[#LinkObject | Link object]]) from the given Object ID.
| |
| | |
| === Create a Link ===
| |
| | |
| PUT <code>/ajax/link?action=new</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: Link object as described in [[#LinkObject | Link object]].
| |
| | |
| Response: An OK.
| |
| | |
| {| id="LinkObject" cellspacing="0" border="1"
| |
| |+ align="bottom" | Link Object
| |
| ! Field !! Name !! Type !! Description
| |
| |-
| |
| | First Object ID || id1 || Number || The ID of the first Object you want to start to link
| |
| |-
| |
| | First Module Type || module1 || Number || The Module of this Object Possible Values:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || Appointment
| |
| |-
| |
| | 4 || Task
| |
| |-
| |
| | 7 || Contact
| |
| |-
| |
| | 13 || Project
| |
| |-
| |
| | 17 || Forum
| |
| |-
| |
| | 18 || Pin board
| |
| |-
| |
| | 19 || Email
| |
| |-
| |
| | 137 || Infostore
| |
| |}
| |
| |-
| |
| | First Folder ID || folder1 || String || The Folder of this Object
| |
| |-
| |
| | Second Object ID || id2 || Number || The ID of the second Object you want to link the first Object with
| |
| |-
| |
| | Second Module Type || module2 || Number || The Module of the second Object
| |
| Possible Values:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || Appointment
| |
| |-
| |
| | 4 || Task
| |
| |-
| |
| | 7 || Contact
| |
| |-
| |
| | 13 || Project
| |
| |-
| |
| | 17 || Forum
| |
| |-
| |
| | 18 || Pin board
| |
| |-
| |
| | 19 || Email
| |
| |-
| |
| | 137 || Infostore
| |
| |}
| |
| |-
| |
| | Second Folder ID || folder2 || String || The Folder of the second Object
| |
| |}
| |
| | |
| === Delete Link ===
| |
| | |
| PUT <code>/ajax/link?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>id</code> – The ID of the base Object
| |
| * <code>module</code> – The type of the Object
| |
| * <code>folder</code> – The Folder of the Object
| |
| | |
| Request body: A List of arrays with the information of the Links to delete which looks like [[#DeleteObject | Delete object]].
| |
| | |
| Response: A List of arrays with object Ids of links which are not readable by the user and were therefore not deleted. See [[#DeleteObject | Delete object]].
| |
| | |
| {| id="DeleteObject" cellspacing="0" border="1"
| |
| |+ align="bottom" | Delete Object
| |
| ! Field !! Type !! Array Position
| |
| |-
| |
| | Object id || Number || 0
| |
| |-
| |
| | Module || Number || 1
| |
| |-
| |
| | Folder || String || 2
| |
| |}
| |
| | |
| == Module "Attachments" ==
| |
| | |
| The Attachment Module allows file attachments to arbitrary objects. Object addresses are defined analogous to the Link module. An Attachment always belongs to an object (called 'attached') in a certain folder of a certain module.
| |
| | |
| === Get All Attachments for an Object ===
| |
| | |
| GET <code>/ajax/attachment?action=all</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>attached</code> – The Object ID of the Object
| |
| * <code>folder</code> – The Folder ID of the Object
| |
| * <code>module</code> – The Module type of the Object
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| | |
| 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.
| |
| | |
| === Get a list of attachments ===
| |
| | |
| PUT <code>/ajax/attachment?action=list</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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]].
| |
| * <code>attached</code> – The Object ID of the Object
| |
| * <code>folder</code> – The Folder ID of the Object
| |
| * <code>module</code> – The Module type of the Object
| |
| | |
| Request body: An array of with object IDs of requested tasks.
| |
| | |
| 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.
| |
| | |
| === Create an Attachment ===
| |
| | |
| POST <code>/ajax/attachment?action=attach</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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]].
| |
| * <code>file_[index]</code> – The file metadata as per <input type=file /> upload.
| |
| | |
| 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.
| |
| | |
| Request body: multipart/form-data or multipart/mixed containing the file data of the attached file and the above fields.
| |
| | |
| 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.
| |
| | |
| {| id="AttachmentObject" cellspacing="0" border="1"
| |
| |+ align="bottom" | Attachment Object
| |
| ! ID !! Name !! Type !! Description
| |
| |-
| |
| | 800 || folder || Number || The ID of the first Folder in which the attached object resides.
| |
| |-
| |
| | 801 || attached || Number || The object id of the object this attachement is attached to.
| |
| |-
| |
| | 802 || module || Number || The Module of this Object Possible Values:
| |
| {| cellspacing="0" border="1"
| |
| | 1 || Appointment
| |
| |-
| |
| | 4 || Task
| |
| |-
| |
| | 7 || Contact
| |
| |-
| |
| | 137 || Infostore
| |
| |}
| |
| |-
| |
| | 803 || filename || String || The filename of the attached file.
| |
| |-
| |
| | 804 || file_size || Number || The file size (in bytes) of the attached file.
| |
| |-
| |
| | 805 || file_mimetype || String || The MIME-Type of the attached file
| |
| |-
| |
| | 806 || rft_flag || Boolean || If the attachment is a RTF Attachment of Outlook. (Outlook descriptions can be stored as RTF Documents).
| |
| |}
| |
| | |
| === Delete Attachment ===
| |
| | |
| PUT <code>/ajax/attachment?action=detach</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>attached</code> – The ID of the base Object
| |
| * <code>module</code> – The type of the Object
| |
| * <code>folder</code> – The Folder of the Object
| |
| | |
| Request body: An array with the ids of the attachments to delete.
| |
| | |
| === Get updated attachments ===
| |
| | |
| GET <code>/ajax/attachment?action=updates</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <code>attached</code> – Object ID of the object to which the attachments are attached.
| |
| * <code>module</code> – Module ID (as per [[#AttachmentObject | Attachment object]]) of the attached object.
| |
| * <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]].
| |
| * <code>sort</code> (optional) – The identifier of a column which determines the sort order of the response. If this parameter is specified, then the parameter order must be also specified.
| |
| * <code>order</code> (optional) – "asc" if the response entires should be sorted in the ascending order, "desc" if the response entries should be sorted in the descending order. If this parameter is specified, then the parameter sort must be also specified.
| |
| * <code>timestamp</code> – Timestamp of the last update of the requested infoitems.
| |
| ignore (optional) – Which kinds of updates should be ignored. Currently, the only valid value – "deleted" – causes deleted object IDs not to be returned.
| |
| | |
| 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 are identified by their object IDs as plain numbers, without being part of a nested array.
| |
| | |
| === Get an attachment ===
| |
| | |
| GET <code>/ajax/attahment?action=get</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <code>attached</code> – Object ID of the object to which the attachments are attached.
| |
| * <code>module</code> – Module ID (as per [[#AttachmentObject | Attachment object]]) of the attached object.
| |
| * <code>id</code> – Object ID of the requested attachment.
| |
| | |
| 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]].
| |
| | |
| === Get an attachments filedata ===
| |
| | |
| GET <code>/ajax/attachment/[filename]?action=document</code>
| |
| | |
| Parameters:
| |
| | |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – Object ID of the folder, whose contents are queried.
| |
| * <code>attached</code> – Object ID of the object to which the attachments are attached.
| |
| * <code>module</code> – Module ID (as per [[#AttachmentObject | Attachment object]]) of the attached object.
| |
| * <code>id</code> – Object ID of the requested attachment.
| |
| * <code>content_type</code> (optional) – If set the responses Content-Type header is set to this value, not the attachements file mime type.
| |
| | |
| 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.
| |
| Note: The Filename may be added to the customary infostore path to suggest a filename to a Save-As dialog.
| |
| | |
| == Module "reminder" ==
| |
| | |
| The reminder module provides the ability to fetch all active reminders for a user between two dates.
| |
| | |
| === Get reminder range ===
| |
| | |
| GET <code>/ajax/reminder?action=range</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>end</code> – The End date of the reminder range
| |
| | |
| Response: An Array with all reminders which are scheduled until the specified time. Each reminder is described in [[#ReminderResponse | Reminder response]].
| |
| | |
| {| id="ReminderResponse" cellspacing="0" border="1"
| |
| |+ align="bottom" | Reminder response
| |
| ! Field !! Type !! Description
| |
| |-
| |
| | object_id || Number || The ID of the reminder.
| |
| |-
| |
| | target_id || Number || The target_id where this reminder is attached to
| |
| |-
| |
| | alarm || Time || The time of the alarm
| |
| |-
| |
| | module || Number || The module of the reminder
| |
| |}
| |
| | |
| === Delete Link ===
| |
| | |
| PUT <code>/ajax/link?action=delete</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Request body: An object with the field “id”.
| |
| | |
| == Module "multiple" ==
| |
| | |
| The multiple module allows to bundle multiple requests to most other modules in a single request. Not supported are:
| |
| * modules login, config and multiple,
| |
| * POST requests with a multipart encoding (uploads),
| |
| * GET requests which do not use an object as described in [[#ResponseBody | Response body]] as response body (downloads).
| |
| | |
| === Multiple requests ===
| |
| | |
| PUT <code>/ajax/multiple</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>continue</code> – Specifies whether processing of requests should stop when an error occurs, or whether all request should be processed regardless of errors.
| |
| | |
| 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.
| |
| | |
| 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]].
| |
| | |
| == Module "quota" ==
| |
| | |
| The filestore module allows accesssing information about the use and quota of the filestore.
| |
| | |
| === Get the filestore usage data ===
| |
| | |
| GET <code>/ajax/quota?action=filestore</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| Response: A JSON Object containing the fields “use” and “quota”. “use” represents the uploaded files sizes sum and the field “quota” represents the maximum.
| |
| | |
| === Get the mail usage data ===
| |
| | |
| GET <code>/ajax/quota?action=mail</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| | |
| 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.
| |
| | |
| | |
| == Module "import"==
| |
| The module import allows to import specific module data (like Contacts, Tasks or Appointments) in several formats (iCal, vCard, CSV) into a folder.
| |
| | |
| === Import CSV ===
| |
| POST <code>/ajax/import?action=CSV</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.
| |
| | |
| 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.
| |
| | |
| === Import iCAL ===
| |
| POST <code>/ajax/import?action=ICAL</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <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.
| |
| | |
| 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.
| |
| | |
| === Import vCard ===
| |
| POST <code>/ajax/import?action=VCARD</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – ObjectID of the folder into which data should be imported. This must be a Contact folder.
| |
| | |
| 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.
| |
| | |
| | |
| == Module "export" ==
| |
| The module export allows to export specific module data (like Contacts, Tasks or Appointments) from a folder in several formats (iCal, vCard, CSV).
| |
| | |
| === Exporting CSV ===
| |
| GET <code>/ajax/export?action=CSV</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Contact folder.
| |
| * <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.
| |
| | |
| Response: An InputStream containing the file of the MIME type <code>text/csv</code>.
| |
| | |
| === Exporting iCAL ===
| |
| GET <code>/ajax/export?action=ICAL</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Contact folder.
| |
| | |
| Response: An InputStream containing the file, of the MIME type <code>text/calendar</code>.
| |
| | |
| === Exporting vCard ===
| |
| GET <code>/ajax/export?action=VCARD</code>
| |
| | |
| Parameters:
| |
| * <code>session</code> – A session ID previously obtained from the login module.
| |
| * <code>folder</code> – ObjectID of the folder whose contents are to be exported. This must be a Contact folder.
| |
| | |
| Response: An InputStream containing the file, of the MIME type <code>text/x-vcard</code>.
| |