Skip to content

GitLab

Last edited by Andrea Pavlovic
Page history

Customers

Clients / Customers / Companies

Unlike the other data, customers (private individual or company) are stored in a specific manner, so that

  • clients (=private individuals) can log in
  • a client may have different agendas (access rights)
  • a vehicle may be owned by either a client or a company

This means that we added plugins to the general queries and transitions, to make it easier or possible at all to administrate and query the data correctly.

Customers - Clients vs Companies

All customers are in core.customer. The "is_client" flag distinguishes actual people ("client") from companies. Storing them both in the same entity allows us to use either as an owner of a vehicle without any further adaptations.

Clients have an attribute "owning_client" (refers system.client, where lots of attributes [i.e. first name, last name] are stored) 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 Clients

#!json

#POST /data/core/customer/query
{
  "conds" : {"me.is_client" : 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_client" : 1},
  "attrs": {"prefetch" : "owning_client"}
}

List Companies

Companies can be retrieved with the equivalent query:

#!json

#POST /data/core/customer/query
{
  "conds" : {"me.is_client" : 0}
}

Client Agendas

There are three client agendas: "admin" (ID: 4), "employee" (ID: 5) and "customer" (ID: 3).

These IDs should not change, but they could in theory.

Only a user with agenda "admin" may change (create/delete) agenda assignments.

To list them:

#!json

POST {{url}}/data/system/agenda/query
{}

To find one:

#!json

POST {{url}}/data/system/agenda/query
{
  "conds": {"name": "employee"}
}

"admin" and "employee" clients have full access to all customer data, employees may have limited access to some edit options.

"customer" clients have access to their and their companies' entries in core.customer, core.vehicle*.

Which API endpoint are available for a client is visible in the universe.

List Admin Clients

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.

Add Agenda

The user calling this must have the "admin" agenda assigned.

#!json

# POST {{url}}/data/system/assignment/transitions/create
{
  "agenda": 10,
  "assigned_client": 34
}

Remove Agenda

The user calling this must have the "admin" agenda assigned.

First, find the id of the assignment of the client to the agenda you want to remove:

#!json

# POST {{url}}/data/system/assignment/query
{
  "conds": {
    "agenda" : 10,
    "assigned_client": 5
  },
  "attrs" : {"columns" : "id"}
}

Then delete the entry using that id:

#!json

# POST {{url}}/data/system/assignment/transitions/12/delete
{}

Administration

Create Client

Parameters (type, required etc) are found in the universe under $.plugins.customer_client_create.

#!json

#POST /plugins/customer_client_create
{
  "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 one from core.customer.

non-admin

Any user may edit it's own entry in core.customer:

#!json

# POST {{url}}/data/core/customer/34/transitions/modify
{
  "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"}]
}

admin

For an admin user, an unbound transition exists:

#!json

# POST {{url}}/data/core/customer/34/transitions/admin_modify_client
{
  "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"}]
}

Using admin_modify_company will work, but only set the attributes allowed there. So better not to use it.

Create Company

#!json

#POST /plugins/customer_company_create
{
  "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"}]
}

Using admin_modify_client will work, but only set the attributes allowed there. So better not to use it.

Client Join Company

The IDs necessary here are die "id" attributes in core.customer.

#!json

#POST {{url}}/plugins/client_company_join
{
  "client_customer_id" : 34,
  "company_id" : 35
}

Client Leave Company

The IDs necessary here are die "id" attributes in core.customer.

#!json

#POST {{url}}/plugins/client_company_leave
{
  "client_customer_id" : 34,
  "company_id" : 35
}

List Clients

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_client = false).

#!json


{{url}}/data/core/customer/query
{
  "conds": {
    "assignment__core_customer__binding_instance_of_customer.assigned_client" : 5,
    "me.is_client" : false
  },
  "attrs" : {"join":"assignment__core_customer__binding_instance_of_customer"}
}

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_client" : true
  },
  "attrs" : {
    "prefetch" : "owning_client",
    "join" : {"owning_client" : "assignment__core_customer__assigned_client"}}
}