From d3c3f2aa982e573434e4b513a915286573991205 Mon Sep 17 00:00:00 2001 From: Richard Steinmetz Date: Tue, 5 Dec 2023 15:50:22 +0100 Subject: [PATCH] feat(developer): document the new out-of-office feature Signed-off-by: Richard Steinmetz --- developer_manual/client_apis/OCS/index.rst | 1 + .../client_apis/OCS/ocs-out-of-office-api.rst | 130 ++++++++++++++++++ developer_manual/digging_deeper/index.rst | 1 + .../digging_deeper/out_of_office.rst | 118 ++++++++++++++++ 4 files changed, 250 insertions(+) create mode 100644 developer_manual/client_apis/OCS/ocs-out-of-office-api.rst create mode 100644 developer_manual/digging_deeper/out_of_office.rst diff --git a/developer_manual/client_apis/OCS/index.rst b/developer_manual/client_apis/OCS/index.rst index af76db8d8c9..db65a3fe4f3 100644 --- a/developer_manual/client_apis/OCS/index.rst +++ b/developer_manual/client_apis/OCS/index.rst @@ -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 diff --git a/developer_manual/client_apis/OCS/ocs-out-of-office-api.rst b/developer_manual/client_apis/OCS/ocs-out-of-office-api.rst new file mode 100644 index 00000000000..d0e43f120d3 --- /dev/null +++ b/developer_manual/client_apis/OCS/ocs-out-of-office-api.rst @@ -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: +*/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 diff --git a/developer_manual/digging_deeper/index.rst b/developer_manual/digging_deeper/index.rst index d0145cdccee..57f4e5e7074 100644 --- a/developer_manual/digging_deeper/index.rst +++ b/developer_manual/digging_deeper/index.rst @@ -43,3 +43,4 @@ Digging deeper profiler deadlock phonenumberutil + out_of_office diff --git a/developer_manual/digging_deeper/out_of_office.rst b/developer_manual/digging_deeper/out_of_office.rst new file mode 100644 index 00000000000..7a60179f108 --- /dev/null +++ b/developer_manual/digging_deeper/out_of_office.rst @@ -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`. + +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, + }