From 46f48d22f3046b4fecb79c97b3cc78bdb0dcd48b Mon Sep 17 00:00:00 2001
From: Benedikt Kulmann <benedikt@kulmann.biz>
Date: Fri, 5 Jun 2020 08:26:02 +0200
Subject: [PATCH] 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 000000000..6272512a9
--- /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.