# 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:
# Devices service
TIP
Available as a global service
WARNING
update
and remove
methods are the only ones allowed from the client side
create
method is only allowed from the server side
create
(respectively remove
) creates (respectively removes) the device to/from the notification system (APNS or Firebase).
update
updates the device registration ID or create it if not yet created.
# Data model
The data model of a device as used by the API is detailed here.
TIP
Devices are store in the devices
property of the user they belong to.
# Hooks
The following hooks are executed on the devices
service:
# Mailer service
TIP
Available as a global service
This service is powered by feathers-mailer (opens new window). 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 (opens new window). 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 (opens new window) and to delegate the domain-wide authority to the service account (opens new window) with scope https://mail.google.com
.
# Hooks
The following hooks are executed on the databases
service:
# Pusher service
TIP
Available as a global service
This service relies on sns-mobile (opens new window), which has a nice tutorial (opens new window), to manage the link between AWS SNS (opens new window) and internal resource objects in order to send push notifications to users.
To get an API access/secret key you need to create a new user in IAM with a role giving access to SNS like AmazonSNSFullAccess
but in production you should control access more precisely (opens new window).
Since 2017 Google Cloud Messaging (GCM) has become Firebase Cloud Messaging (FCM), to generate an API key follow this issue (opens new window) and enter the server key when creating the SNS application on AWS. Although you use the Firebase console you should also see the created API through the Google Cloud console.
WARNING
create
and remove
methods are the only one allowed from the server side
# Data model
This service helps (un)registering devices to/from SNS and create/remove SNS topics. This service also helps associating a resource object (e.g. a group) with a SNS topic to provide push notifications to the users associated with the resource. SNS ARNs are directly stored on the target resource(s) in the topics
property.
TIP
The service is designed to possibly manage a different topic per platform (e.g. ANDROID / IOS), although at the present time the same topic is used by all platforms because by default SNS topics are cross-platforms.
For instance the topics associated to a group will result in the following structure on the group object:
{
_id: ObjectId('5f568ba1fc54a1002fe6fe37'),
name: 'Centre de Castelnaudary',
topics: {
ANDROID: 'arn:aws:sns:eu-west-1:xxx',
IOS: 'arn:aws:sns:eu-west-1:xxx'
}
}
Last but not least, This service helps publishing messages to SNS devices or topics.
As a consequence, the create
/remove
operations have to be called with an action
property indicating the target SNS operations among device
, topic
, subscriptions
and message
. The payload varies according to the selected target operation:
device
:- device as data: device object with SNS ARN and/or registration ID (i.e. token) for APNS or Firebase
topic
:- pushObject as params: target resource owing the topic
- pushService as params: target resource service
- topicField as data/query: target property to store the topic
subscriptions
- pushObject as params: target resource owing the topic
- users as params: target subject(s) to subscribe to topic
- topicField as data/query: target property to store the topic
message
- pushObject as params: target resource owing the topic if topic
- pushService as params: target resource service
- message as data: message payload
# Hooks
The following hooks are executed on the pusher
service:
# Account service
TIP
Available as a global service
This service is powered by feathers-authentication-management (opens new window).
# 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 (opens new window).
# Hooks
The following hooks are executed on the account
service:
# Testing
To make test run we need two gmail accounts:
email-notifications@kalisio.com
used as email sendertest@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 thetest@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 (opens new window), 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 (opens new window) and here (opens new window).
Details on how to use Google APIs from Node.js here (opens new window).
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 (opens new window).
# 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:
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:
# 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
The following hooks are executed on the tags
service:
# Storage service
TIP
Available as a global and a contextual service
WARNING
get
, create
and remove
methods are the only one allowed from the client/server side
Blobs can be created directly using this service or through "attachment" to a target resource (e.g. a user).
This service heavily relies on feathers-blob (opens new window) and multer (opens new window) for handling multipart/form-data (opens new window).
# Data model
No data model, data are directly stored on target storage backend (i.e. AWS S3).
# Hooks
The following hooks are executed on the storage
service:
# Databases service
TIP
Available as a global service
This service is powered by feathers-mongodb-management (opens new window). 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:
# 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:
{
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 specific hooks are executed on the organisations
service.
# 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 specific 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
The following hooks are executed on the groups
service:
# Local settings service
This client-side service allows to restore/save persistent settings to/from the global store from/to local storage (opens new window).
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:
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:
{
"$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"]
}
← Application Hooks →