KDK

Appearance

Services ​

Users service ​

TIP

Available as a global service

Data model ​

The data model of a user as used by the API is detailed here.

Hooks ​

The following hooks are executed on the users service:

null

Mailer service ​

TIP

Available as a global service

This service is powered by feathers-mailer. It acts as a proxy to send emails through an SMTP server.

WARNING

Service methods are only allowed from the server side. create is the sole available method used to send an email.

DEPRECATION NOTICE

The email account can authorise connection by email/password on https://myaccount.google.com/lesssecureapps. Before that the domain admin should allow him to manage this setting (Admin Console > Security > General > Less secure apps settings). To avoid changing it for all users first create a group, add the user to the group and let the group manage less secure apps setting.

On 15 february 2021 Gmail API requires OAuth2 authentication to send emails. The simplest solution is to create a service account and to delegate the domain-wide authority to the service account with scope https://mail.google.com.

Hooks ​

The following hooks are executed on the databases service:

null

Push service ​

This service is powered by feathers-webpush.

TIP

Available as a global service

WARNING

Service methods are only allowed from the server side. create is the sole available method used to send a notification.

Data model ​

Subscription and notification data model is provided by feathers-webpush.

Hooks ​

The following hooks are executed on the push service:

null

Account service ​

TIP

Available as a global service

This service is powered by feathers-authentication-management.

Data model ​

This service consists in associating verification tokens to users so that they can safely reset their password or change their email, please refer to feathers-authentication-management docs.

Hooks ​

The following hooks are executed on the account service:

null

Testing ​

To make test run we need two gmail accounts:

  • email-notifications@kalisio.com used as email sender
  • test@kalisio.com used as user test email

When testing identity change we also use the test@kalisio.xyz address as user test email. However to avoid creating a new account in Google you can simply add an alias for this address to the test@kalisio.com account.

The first email account is used by the mailer service to send email notifications. The second email account requires OAuth2 authentication to be able to read emails using the GMail API. The simplest way is by creating a service account for a JWT-based authentication. Interesting issue to make all the configuration work can be found here, notably you have to delegate domain-wide authority to the service account in order to authorize your app to access user data on behalf of users and authorise the client ID of the service account with scopes https://mail.google.com/,https://www.googleapis.com/auth/gmail.readonly.

Standard OAuth2 with refresh token might also be used as detailed here and here.

Details on how to use Google APIs from Node.js here.

Some anti-virus or firewalls softwares intercept HTTPS traffic, decrypting it, and then encrypting it using a self-signed certificate causing a "Self-Signed Certificate in Certificate Chain" error. If so deactivate the SSL analysys in your software, this might help.

Authorisations service ​

TIP

Available as a global service

WARNING

create and remove methods are the only one allowed from the client/server side

Data model ​

An authorisation consists in associating a resource object (e.g. a group) with a subject object (e.g. a user) according to a permission (i.e. a role or a right). The resource object information and the permission are directly stored on the target subject(s) in a property called the scope of the authorisation (e.g. groups to store all groups a user belongs to).

For instance the groups a user belongs to with different roles will result in the following structure on the user:

js
groups: [
  {
      _id: ObjectId('5f568ba1fc54a1002fe6fe37'),
      name: 'Centre de Castelnaudary',
      context: '5f55f4169f6d47002f05f4ac',
      permissions: 'owner'
      ...
  },
  {
      _id: ObjectId('5f64a3791a1714002f68437d'),
      name: 'Kalisio',
      context: '5f532d439f6d47002f04f07e',
      permissions: 'manager'
      ...
  },
  {
      _id: ObjectId('5f65e34a75b663003095f52e'),
      name: 'LTD',
      context: '5f65d98084f9d5003039b55b',
      permissions: 'member'
      ...
  }
]

Hooks ​

The following hooks are executed on the authorisations service:

null

Tags service ​

TIP

Available as a global and a contextual service

Tags can be created directly using this service or by "tagging" a target resource (e.g. a user). As a consequence, create/remove operations can include a target resource as input data/ID.

Due to this behaviour tags are created/removed by value, not by ID. To avoid duplication when tagging multiple resources with the same tag, the service manages a reference count on tag objects and they are automatically created/removed accordingly.

WARNING

remove method can be called with a resource ID

Data model ​

The data model of a tag as used by the API is detailed here.

Hooks ​

There is no internal hook executed on this service, typically the following hooks can be executed on the tags service for an application:

null

Storage service ​

TIP

Available as a global and a contextual service

WARNING

From the client side and even if most of the methods are available, we higly recomment to use the helper functions provide by the storage singleton.

Blobs can be created directly using this service or through "attachment" to a target resource (e.g. a user).

This service relies on feathers-s3

Data model ​

No data model, data are directly stored on target storage backend.

Hooks ​

The following hooks are executed on the storage service:

null

Import-Export service ​

TIP

Available as a global service

WARNING

create methods are the only one allowed from the client side

This service relies on feathers-import-export library.

INFO

The import-export service instanciantes its own S3 service to avoid mixing temporary objects with the objects you want to manage with the Storage service

Data model ​

No data model, data are directly stored on a storage backend (i.e. AWS S3).

Hooks ​

null

TIP

For performance issues, we do not recommend to install after/before hooks to trasnform the data before importing/exporting. You can install your own transaformation functions.

Databases service ​

TIP

Available as a global service

This service is powered by feathers-mongodb-management. It acts as a proxy to perform MongoDB operations like creating databases, collections or users.

WARNING

Service methods are only allowed from the server side

Hooks ​

The following hooks are executed on the databases service:

null

Organisations service ​

TIP

Available as a global service

This service exhibits the following methods in addition to standard CRUD operations:

  • createOrganisationServices: creates all registered services for an organisation
  • removeOrganisationServices: removes registered services for an organisation
  • registerOrganisationServicesHook(hook): register a function to create additional services per organisation
  • unregisterOrganisationServicesHook(hook): unregister a previously registered function

A hook function has the following structure:

js
{
  createOrganisationServices: function(organisation, db)
  removeOrganisationServices: function(organisation, db)
}

TIP

By default the following services are created for an organisation: members, tags, groups, storage.

Data model ​

The data model of an organisation as used by the API is detailed here.

Hooks ​

No internal hooks are executed on the organisations service, typically the following hooks can be executed on the organisations service for an application:

null

Members service ​

TIP

Available as a contextual service

This service is a proxy to the users service available at the organisation level in order to filter users belonging to it.

Data model ​

The data model of a member as used by the API is a the one of a user.

Hooks ​

No internal hooks are executed on the members service.

Groups service ​

TIP

Available as a contextual service

Data model ​

The data model of a group as used by the API is detailed here.

Hooks ​

There is no internal hook executed on this service, typically the following hooks can be executed on the groups service for an application:

null

Local settings service ​

This client-side service allows to restore/save persistent settings to/from the global store from/to local storage.

WARNING

get and patch methods are the only one allowed, id parameter is ignored and methods will always target the whole settings object

WARNING

This service has to be instanciated at application level, none provided by default

To create your own service use the following code:

js
import { Store, LocalSettingsService } from '@kalisio/kdk/core.client'

// Setup defaults in global store
Store.set('app-settings', { x: y, ... })
// Create a service targeting only settings in store
const settingsService = api.createService('settings', {
  service: LocalSettingsService,
  propertyMapping: {
    x: 'app-settings.x',
    ...
  }
})
// Restore previous settings from local storage if any
settingsService.restoreSettings()

TIP

Because settings are available through a service interface you can edit it using the editor system. The propertyMapping will be used to match form field names and corresponding global store properties.

For instance the following schema can be used to edit the previous sample:

json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "http://www.kalisio.xyz/schemas/settings.update.json#",
  "title": "schemas.UPDATE_SETTINGS_TITLE",
  "type": "object",
  "properties": {
    "x": {
      "type": "string", 
      "field": {
        "component": "form/KTextField",
        "helper": "schemas.X_FIELD_LABEL"
      }
    }
  },
  "required": ["x"]
}

MIT Licensed | Copyright © 2017-20xx Kalisio