khanh.pndc/nextcloud-docs
1
0
Fork 0
mirror of https://github.com/nextcloud/documentation.git synced 2026-01-02 17:59:36 +07:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #11367 from nextcloud/feat/developer/out-of-office

Browse Source 
feat(developer): document the new out-of-office feature
This commit is contained in:
Richard Steinmetz
2023-12-05 16:08:26 +01:00
committed by GitHub
parent ee0b62df27 6a2861b5fe
commit 22284a19de
4 changed files with 250 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
developer_manual/client_apis/OCS/index.rst
View File

@@ -20,3 +20,4 @@ The old documentation is still kept as it provides some additional documentation
ocs-translation-api
ocs-textprocessing-api
ocs-text2image-api
ocs-out-of-office-api

130
developer_manual/client_apis/OCS/ocs-out-of-office-api.rst Normal file
View File

@@ -0,0 +1,130 @@
.. _ocs-out-of-office-api:
=====================
OCS Out-of-office API
=====================
.. versionadded:: 28.0
The OCS Out-of-office API allows you to access and modify out-of-office data of users.
The base URL for all calls to the share API is:
*<nextcloud_base_url>/ocs/v2.php/apps/dav/api/v1/outOfOffice*
All calls to OCS endpoints require the ``OCS-APIRequest`` header to be set to ``true``.
Fetch ongoing data
------------------
Fetch data of the ongoing out-of-office period of a user.
* Method: ``GET``
* Endpoint: ``/{userId}``
* Response:
- Status code:
+ ``200 OK`` Out-of-office data
+ ``404 Not Found`` If the user does not have an ongoing out-of-office period
- Data (is only sent if the status code is ``200 OK``):
+--------------+--------+---------------------------------------------------------------------+
| field | type | Description |
+--------------+--------+---------------------------------------------------------------------+
| ``id`` | int | Database ID of the absence data entity |
+--------------+--------+---------------------------------------------------------------------+
| ``userId`` | string | ID of the user which the data belongs to |
+--------------+--------+---------------------------------------------------------------------+
| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``lastDay`` | string | Last day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``status`` | string | Short text that is set as user status during the absence |
+--------------+--------+---------------------------------------------------------------------+
| ``message`` | string | Longer multiline message that is shown to others during the absence |
+--------------+--------+---------------------------------------------------------------------+
Fetch upcoming or ongoing data
------------------------------
The returned out-of-office period might not have started yet. This endpoint will return data of the
ongoing or next upcoming out-of-office period of a user.
* Method: ``GET``
* Endpoint: ``/{userId}``
* Response:
- Status code:
+ ``200 OK`` Out-of-office data
+ ``404 Not Found`` If the user did not schedule an out-of-office period
- Data (is only sent if the status code is ``200 OK``):
+--------------+--------+---------------------------------------------------------------------+
| field | type | Description |
+--------------+--------+---------------------------------------------------------------------+
| ``id`` | int | Database ID of the absence data entity |
+--------------+--------+---------------------------------------------------------------------+
| ``userId`` | string | ID of the user which the data belongs to |
+--------------+--------+---------------------------------------------------------------------+
| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``lastDay`` | string | Last day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``status`` | string | Short text that is set as user status during the absence |
+--------------+--------+---------------------------------------------------------------------+
| ``message`` | string | Longer multiline message that is shown to others during the absence |
+--------------+--------+---------------------------------------------------------------------+
Modify out-of-office data
-------------------------
It is only possible to modify out-of-office data of the currently logged in user.
* Method: ``POST``
* Endpoint: ``/``
* Data:
+--------------+--------+---------------------------------------------------------------------+
| field | type | Description |
+--------------+--------+---------------------------------------------------------------------+
| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``lastDay`` | string | Last day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``status`` | string | Short text that is set as user status during the absence |
+--------------+--------+---------------------------------------------------------------------+
| ``message`` | string | Longer multiline message that is shown to others during the absence |
+--------------+--------+---------------------------------------------------------------------+
* Response:
- Status code:
+ ``200 OK`` Updated out-of-office data
+ ``400 Bad Request`` If the first day is not before the last day
+ ``401 Unauthorized`` If the user is not logged in
- Data (is only sent if the status code is ``200 OK``):
+--------------+--------+---------------------------------------------------------------------+
| field | type | Description |
+--------------+--------+---------------------------------------------------------------------+
| ``id`` | int | Database ID of the absence data entity |
+--------------+--------+---------------------------------------------------------------------+
| ``userId`` | string | ID of the user which the data belongs to |
+--------------+--------+---------------------------------------------------------------------+
| ``firstDay`` | string | First day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``lastDay`` | string | Last day of the absence in format ``YYYY-MM-DD`` |
+--------------+--------+---------------------------------------------------------------------+
| ``status`` | string | Short text that is set as user status during the absence |
+--------------+--------+---------------------------------------------------------------------+
| ``message`` | string | Longer multiline message that is shown to others during the absence |
+--------------+--------+---------------------------------------------------------------------+
Clear data and disable out-of-office
------------------------------------
It is only possible to clear out-of-office data of the currently logged in user.
* Method: ``DELETE``
* Endpoint: ``/``
* Response:
- Status code:
+ ``200 OK`` Out-of-office data was cleared
+ ``401 Unauthorized`` If the user is not logged in

1
developer_manual/digging_deeper/index.rst
View File

@@ -43,3 +43,4 @@ Digging deeper
profiler
deadlock
phonenumberutil
out_of_office

118
developer_manual/digging_deeper/out_of_office.rst Normal file
View File

@@ -0,0 +1,118 @@
=====================
Out-of-office periods
=====================
.. versionadded:: 28.0
Since Nextcloud 28, users may set their out-of-office periods in their personal settings. The data
can be accessed and modified by Nextcloud Apps via OCP and by clients via OCS. Nextcloud Apps can
also listen to events emitted by the out-of-office feature.
The OCS API is documented in the :ref:`client section<ocs-out-of-office-api>`.
Access data from within a Nextcloud App via OCP
-------------------------------------------------
The out-of-office data can be accessed through the `OCP\\User\\IAvailabilityCoordinator`
interface. It provides the following methods:
.. code-block:: php
/**
* Check if the feature is enabled on this instance
*/
public function isEnabled(): bool;
.. code-block:: php
/**
* Get the user's ongoing out-of-office data, if any
*/
public function getCurrentOutOfOfficeData(IUser $user): ?IOutOfOfficeData;
.. code-block:: php
/**
* Reset the absence cache to null
*/
public function clearCache(string $userId): void;
.. code-block:: php
/**
* Is the absence in effect at this moment
*/
public function isInEffect(IOutOfOfficeData $data): bool;
Listening to events
-------------------
All events have one common method to retrieve data about the affected out-of-office period.
.. code-block:: php
public function getData(): IOutOfOfficeData;
The following events are emitted by the out-of-office feature:
* ``OCP\User\Events\OutOfOfficeScheduledEvent`` If a new out-of-office period is scheduled for a
user. This event is only emitted once when there was no out-of-office period before.
* ``OCP\User\Events\OutOfOfficeChangedEvent`` If the out-of-office data of a user is changed.
* ``OCP\User\Events\OutOfOfficeDeletedEvent`` If the out-of-office period of a user is deleted.
* ``OCP\User\Events\OutOfOfficeStartedEvent`` If an out-of-office period starts. This event is only
emitted once and not if a period starting in the past is created.
* ``OCP\User\Events\OutOfOfficeEndedEvent`` If an out-of-office period ends. This event is only
emitted once and not if a period ending in the past is created.
Common data structure
---------------------
The OCP API and emitted events share a common data structure `OCP\\User\\IOutOfOfficeData`. The
start and end dates are represented as UNIX timestamps.
.. code-block:: php
interface IOutOfOfficeData extends JsonSerializable {
/**
* Get the unique token assigned to the current out-of-office event
*/
public function getId(): string;
public function getUser(): IUser;
/**
* Get the accurate out-of-office start date
*
* This event is not guaranteed to be emitted exactly at start date
*/
public function getStartDate(): int;
/**
* Get the (preliminary) out-of-office end date
*/
public function getEndDate(): int;
/**
* Get the short summary text displayed in the user status and similar
*/
public function getShortMessage(): string;
/**
* Get the long out-of-office message for auto responders and similar
*/
public function getMessage(): string;
}
It can be serialized to a JSON object with the following structure:
.. code-block::
{
id: string,
userId: string,
startDate: int,
endDate: int,
shortMessage: string,
message: string,
}