From a69d4e0421b5a7d25c3600cb2fe6c93a8edc0c65 Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Fri, 5 Jun 2020 07:43:50 +0200 Subject: [PATCH 1/6] Improve settings docs overview page --- docs/_index.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/_index.md b/docs/_index.md index ed4cf502..9e70356d 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -23,22 +23,24 @@ graph TD ows[ocis-web-settings] owc[ocis-web-core] end - ows ---|"listSettingsBundles(),
listSettingsValues(),
saveSettingsValue(value)"| os[ocis-settings] - owc ---|"listSettingsValues()
getSettingsValue(id)"| sdk[oC SDK] + ows ---|"listSettingsBundles(),
saveSettingsValue(value)"| os[ocis-settings] + owc ---|"listSettingsValues()"| sdk[oC SDK] sdk --- sdks{ocis-settings
available?} sdks ---|"yes"| os sdks ---|"no"| defaults[Use set of
default values] - oa[oCIS extensions
e.g. ocis-accounts] ---|"saveSettingsBundle(bundle),
getSettingsValue(id)"| os + oa[oCIS extensions
e.g. ocis-accounts] ---|"saveSettingsBundle(bundle)"| os {{< /mermaid >}} The diagram shows how the settings service integrates into oCIS: + **Settings management:** -- oCIS extensions can register settings bundles with the ocis-settings service. -- The settings frontend can be plugged into ocis-web, showing generated forms for changing settings values as a user. +- oCIS extensions can register *settings bundles* with the ocis-settings service. +- The settings frontend can be plugged into ocis-web, showing forms for changing *settings values* as a user. +The forms are generated from the registered *settings bundles*. **Settings usage:** -- Extensions can query ocis-settings for settings values of a user. -- The ownCloud SDK, used as a data abstraction layer for ocis-web, will query ocis-settings for settings values of a user, +- Extensions can query ocis-settings for *settings values* of a user. +- The ownCloud SDK, used as a data abstraction layer for ocis-web, will query ocis-settings for *settings values* of a user, if it's available. The SDK uses sensible defaults when ocis-settings is not part of the setup. For compatibility with ownCloud 10, a migration of ownCloud 10 settings into the storage of ocis-settings will be available. From 46f48d22f3046b4fecb79c97b3cc78bdb0dcd48b Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Fri, 5 Jun 2020 08:26:02 +0200 Subject: [PATCH 2/6] Add settings values documentation --- docs/values.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/values.md diff --git a/docs/values.md b/docs/values.md new file mode 100644 index 00000000..6272512a --- /dev/null +++ b/docs/values.md @@ -0,0 +1,73 @@ +--- +title: "Settings Values" +date: 2020-05-04T00:00:00+00:00 +weight: 51 +geekdocRepo: https://github.com/owncloud/ocis-settings +geekdocEditPath: edit/master/docs +geekdocFilePath: values.md +--- + +A **Settings Value** is the value, an authenticated user has chosen for a specific setting, defined in a +*settings bundle*. For choosing settings values as a user, the sole entry point is the ocis-web extension +provided by this service. + +## Identifying settings values + +A *settings value* is uniquely identified by four attributes. Three of them are coming from the setting within +it's settings bundle (see [Settings Bundles](https://owncloud.github.io/extensions/ocis_settings/bundles/) for +an example). The fourth identifies the user. +- extension: Key of the extension that registered the settings bundle, +- bundleKey: Key of the settings bundle, +- settingKey: Key of the setting as defined within the bundle, +- accountUuid: The UUID of the authenticated user who has saved the setting. + +When requests are going through `ocis-proxy`, the accountUuid attribute can be set to the static keyword `me` +instead of using a real UUID. `ocis-proxy` will take care of minting the UUID of the authenticated user into +a JWT, providing it in the HTTP header as `x-access-token`. That UUID is then used in this service, to replace +`me` with the actual UUID of the authenticated user. + +## Example of stored settings values + +```json +{ + "values": { + "language": { + "identifier": { + "extension": "ocis-accounts", + "bundleKey": "profile", + "settingKey": "language", + "accountUuid": "5681371f-4a6e-43bc-8bb5-9c9237fa9c58" + }, + "listValue": { + "values": [ + { + "stringValue": "de" + } + ] + } + }, + "timezone": { + "identifier": { + "extension": "ocis-accounts", + "bundleKey": "profile", + "settingKey": "timezone", + "accountUuid": "5681371f-4a6e-43bc-8bb5-9c9237fa9c58" + }, + "listValue": { + "values": [ + { + "stringValue": "Europe/Berlin" + } + ] + } + } + } +} +``` + +## gRPC endpoints +The obvious way of modifying settings is the ocis-web extension, as described earlier. However, services can +use the respective gRPC endpoints of the `ValueService` to query and modify *settings values* as well. +The gRPC endpoints require the same identifier attributes as described above, so for making a request to +the `ValueService` you will have to make sure that the accountUuid of the authenticated user is available in +your service at the time of the request. From 19e7edfd6b6751010ede8e6d2327e7537778c55c Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Fri, 5 Jun 2020 08:26:17 +0200 Subject: [PATCH 3/6] Add settings values to glossary --- docs/glossary.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/glossary.md b/docs/glossary.md index 4a90da33..8a8095f3 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -33,3 +33,10 @@ In the context of this extension and oCIS in general, we are using the following - Collection of related settings - Registered by an ocis extension + +### Settings Value + +- Manifestation of a setting for a specific user +- E.g. used for customization (at runtime) in `ocis-web` +- `ocis-web` extension for modifying settings values is provided by this service +- Can be queried and modified by other ocis extensions From a01cb60f5a48388eeb11e54cd1781b2b0e606c7c Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Fri, 5 Jun 2020 08:31:03 +0200 Subject: [PATCH 4/6] Small improvements --- docs/values.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/values.md b/docs/values.md index 6272512a..9e03c681 100644 --- a/docs/values.md +++ b/docs/values.md @@ -7,24 +7,26 @@ geekdocEditPath: edit/master/docs geekdocFilePath: values.md --- -A **Settings Value** is the value, an authenticated user has chosen for a specific setting, defined in a -*settings bundle*. For choosing settings values as a user, the sole entry point is the ocis-web extension +A **Settings Value** is the value an authenticated user has chosen for a specific setting, defined in a +*settings bundle*. For choosing settings values as a user the sole entry point is the ocis-web extension provided by this service. ## Identifying settings values -A *settings value* is uniquely identified by four attributes. Three of them are coming from the setting within -it's settings bundle (see [Settings Bundles](https://owncloud.github.io/extensions/ocis_settings/bundles/) for -an example). The fourth identifies the user. +A *settings value* is uniquely identified by four attributes. Three of them are coming from the definition of +the setting within it's settings bundle (see [Settings Bundles](https://owncloud.github.io/extensions/ocis_settings/bundles/) +for an example). The fourth identifies the user. - extension: Key of the extension that registered the settings bundle, - bundleKey: Key of the settings bundle, - settingKey: Key of the setting as defined within the bundle, - accountUuid: The UUID of the authenticated user who has saved the setting. +{{< hint info >}} When requests are going through `ocis-proxy`, the accountUuid attribute can be set to the static keyword `me` instead of using a real UUID. `ocis-proxy` will take care of minting the UUID of the authenticated user into a JWT, providing it in the HTTP header as `x-access-token`. That UUID is then used in this service, to replace `me` with the actual UUID of the authenticated user. +{{< /hint >}} ## Example of stored settings values From 99ee6f101154267a3d42fcb8d60de2cd0b4e4874 Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Fri, 5 Jun 2020 08:33:03 +0200 Subject: [PATCH 5/6] Add changelog item --- changelog/unreleased/docs.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 changelog/unreleased/docs.md diff --git a/changelog/unreleased/docs.md b/changelog/unreleased/docs.md new file mode 100644 index 00000000..a95ab70a --- /dev/null +++ b/changelog/unreleased/docs.md @@ -0,0 +1,6 @@ +Enhancement: Extend the docs + +We have extended the documentation by adding a chapter about settings values. + +https://github.com/owncloud/ocis-settings/issues/11 +https://github.com/owncloud/ocis-settings/pulls/28 From f229f1106c24a9afab54bf063ed7c2a7b687ed6f Mon Sep 17 00:00:00 2001 From: Benedikt Kulmann Date: Mon, 8 Jun 2020 15:11:17 +0200 Subject: [PATCH 6/6] Fixed ocis-web-settings extension name in glossary --- docs/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/glossary.md b/docs/glossary.md index 8a8095f3..ffc9d861 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -38,5 +38,5 @@ In the context of this extension and oCIS in general, we are using the following - Manifestation of a setting for a specific user - E.g. used for customization (at runtime) in `ocis-web` -- `ocis-web` extension for modifying settings values is provided by this service +- `ocis-web-settings` extension for modifying settings values is provided by this service - Can be queried and modified by other ocis extensions