Customers.md

+# Clients / Customers / Companies
+
+[TOC]
+
+## Customers - Clients vs Companies
+
+All customers are in **core.customer**. The "is_private" flag distinguishes actual people ("client") from companies.
+
+Clients have an attribute "owning_client" (refers **system.client**) and can log in with their email address. A user may belong to one or more companies.
+
+Companies do not have an "owning_client" and cannot log in. Any client belonging to a company may see the company's data.
+
+### List Customers
+
+```
+#!json
+
+#POST /data/core/customer/query
+{
+  "conds" : {"me.is_private" : 1}
+}
+```
+
+Private customers have an entry in system.client, which allows them to log into the system. Here, 
+additional attributes are stored and can be joined to the entry in core.customer:
+
+```
+#!json
+
+#POST /data/core/customer/query
+{
+  "conds" : {"me.is_private" : 1},
+  "attrs": {"prefetch" : "owning_client"}
+}
+```
+Companies can be retrieved with the equivalent query:
+```
+#!json
+
+#POST /data/core/customer/query
+{
+  "conds" : {"me.is_private" : 0},
+  "attrs": {"prefetch" : "owning_client"}
+}
+```
+(Joins/Prefetch are left joins, so this works as long as the user has access to the entity)
+
+## Client groups
+
+There are two client groups: "admin" and "customer".
+
+"admin" clients have full access to all **core.*** data. 
+
+"customer" clients have access to their and their companies' entries in **core.customer**, **core.vehicle***.
+
+### List Admin Customers
+
+Admin Customers are those who have the agenda "admin" assigned to them. So, to list them, first join "owning_client" and then for this client, the assignments ("system__assignment__assigned_client"). Then filter out agenda "admin" (which has ID 10).
+
+```
+#!json
+
+# POST {{url}}/data/core/customer/query
+{
+  "conds" : {
+     "system__assignment__assigned_client.agenda" : 10
+  },
+  "attrs": {
+      "join" : {
+          "owning_client" : "system__assignment__assigned_client"
+      }
+   }
+}
+```
+Note that this query only returns the relevant data for the main query - core.customer. The join is used for filtering only. "prefetch" instead of "join" would return the data from system.client and system.assignment as well.
+
+## Administration
+
+### Create Client
+
+Parameters (type, required etc) are found in the universe under $.plugins.customer_private_add.
+```
+#!json
+
+#POST /plugins/customer_private_add
+{
+  "salutation" : "Mr",
+  "first_name":"John",
+  "last_name":"Bean",
+  "email":"mr@bean.com",
+  "phonenumbers": [{"Name": "Mobil", "Nummer":"+43 676 99 88 777"}],
+  "addresses": [{"Name":"Home", "Straße":"Oxford St", "PLZ":"SQ5 9DQ", "Stadt":"London", "Land":"England"}],
+  "password": "supersecure", 
+  "identifier": "id_mr_bean",
+  "is_admin": false, 
+  "locked": false
+}
+```
+### Edit Client
+
+As some data is stored in system.client and some additional data in core.company, two transitions are necessary to access all data.
+
+In system.client any attributes this system table has per default, can be edited. The id here (36 in the url) is the owning_client in core.customer.
+
+```
+#!json
+
+# POST {{url}}/data/system/client/36/transitions/edit
+{
+  "first_name":"Johnny",
+  "last_name":"Bean",
+  "email":"mr@bean.com",
+  "password": "supersecure", 
+  "locked": false
+}
+```
+
+The other attributes have been added for this project and can be changed in core.customer. The id is the on from core.customer.
+
+```
+#!json
+
+# POST {{url}}/data/core/customer/34/transitions/admin_modify_customer
+{
+  "salutation" : "Mr",
+  "phonenumbers": [{"Name": "Mobil", "Nummer":"+43 676 99 88 777"}],
+  "addresses": [{"Name":"Home", "Straße":"Oxford St", "PLZ":"SQ5 9DQ", "Stadt":"London", "Land":"England"}]
+}
+```
+### Create Company
+
+```
+#!json
+
+#POST /plugins/customer_company_add
+{
+  "uid":"google_uid",
+  "name" : "Google Inc",
+  "identifier": "id_google",
+  "phonenumbers": [{"Name": "Mobil", "Nummer":"+43 676 99 88 777"}],
+  "addresses": [{"Name":"Home", "Straße":"Oxford St", "PLZ":"SQ5 9DQ", "Stadt":"London", "Land":"Österreich"}]
+}
+
+```
+### Edit Company
+
+As there is no entry in system.client, admin_modify_company is the only transition necessary.
+
+```
+#!json
+#POST {{url}}/data/core/customer/34/transitions/admin_modify_company
+{
+  "uid":"google_uid",
+  "name" : "Google Inc",
+  "phonenumbers": [{"Name": "Mobil", "Nummer":"+43 676 99 88 777"}],
+  "addresses": [{"Name":"Home", "Straße":"Oxford St", "PLZ":"SQ5 9DQ", "Stadt":"London", "Land":"Österreich"}]
+}
+
+```
+
+### Customer Join Company
+
+The IDs necessary here are die "id" attributes in core.customer.
+
+```
+#!json
+
+#POST {{url}}/plugins/customer_company_join
+{
+  "customerId" : 34,
+  "companyId" : 35
+}
+```
+
+### Customer Leave Company
+The IDs necessary here are die "id" attributes in core.customer.
+
+```
+#!json
+
+#POST {{url}}/plugins/customer_company_leave
+{
+  "customerId" : 34,
+  "companyId" : 35
+}
+```
+### List Client Companies
+
+To list all companies a client is assigned to - get those entries from core.customers which are assigned to the client (5 = system.client.id = core.customer.owning_client) and which are labeled as companies (is_private = false).
+```
+#!json
+
+
+{{url}}/data/core/customer/query
+{
+  "conds": {
+    "assignment__core_customer__binding_instance_of_customer.assigned_client" : 5,
+    "me.is_private" : false
+  },
+  "attrs" : {"join":"assignment__core_customer__binding_instance_of_customer"}
+}
+```
+
+Currently, there is a plugin implementing this query, but it only returns the ids of the companies. This may disappear. The id here is from core.customer.
+
+```
+#!json
+
+# POST {{url}}/plugins/customer_companies_list 
+{
+  "customerId": 34
+}
+```
+
+### List Company Clients
+
+To list all clients assigned to a company, join system.client via owning_client and onto that assignment.core_customer, filtering on the customer there.
+
+```
+#!json
+
+# POST {{url}}/data/core/customer/query
+{
+  "conds": {
+    "assignment__core_customer__assigned_client.binding_instance_of_customer" : 4,
+    "me.is_private" : true
+  },
+  "attrs" : {
+    "prefetch" : "owning_client",
+    "join" : {"owning_client" : "assignment__core_customer__assigned_client"}}
+}
+```
+
+
+Currently, there is a plugin implementing this query, but it only returns the ids of the clients. This may disappear.
+
+
+```
+#!json
+
+# POST {{url}}/plugins/company_customers_list 
+{
+  "companyId": 5
+}
+```
+
+### Add Admin to Client
+
+
+```
+#!json
+
+# POST {{url}}/data/system/assignment/transitions/create
+{
+  "agenda": 10,
+  "assigned_client": 34
+}
+```
+
+## Remove Admin for Client
\ No newline at end of file