Merge pull request #28 from owncloud/docs-about-values

Docs about values

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

docs/_index.md

@@ -23,22 +23,24 @@ graph TD
         ows[ocis-web-settings]
         owc[ocis-web-core]
     end
-    ows ---|"listSettingsBundles(),<br>listSettingsValues(),<br>saveSettingsValue(value)"| os[ocis-settings]
-    owc ---|"listSettingsValues()<br>getSettingsValue(id)"| sdk[oC SDK]
+    ows ---|"listSettingsBundles(),<br>saveSettingsValue(value)"| os[ocis-settings]
+    owc ---|"listSettingsValues()"| sdk[oC SDK]
     sdk --- sdks{ocis-settings<br>available?}
     sdks ---|"yes"| os
     sdks ---|"no"| defaults[Use set of<br>default values]
-    oa[oCIS extensions<br>e.g. ocis-accounts] ---|"saveSettingsBundle(bundle),<br>getSettingsValue(id)"| os
+    oa[oCIS extensions<br>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.

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-settings` extension for modifying settings values is provided by this service
+- Can be queried and modified by other ocis extensions

docs/values.md

@@ -0,0 +1,75 @@
+---
+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 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
+
+```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.