Evénements et alertes

L'API Data v1 vous permet de transmettre des événements et alertes sur intentPlatform. Les utilisateurs d'intentPlatform pourront ensuite définir des règles pour être notifié (mail, sms, etc.) en cas d'alertes transmises sur la plateforme.

Fonctionnement

La transmission d'événements sur intentPlatform se fait sous la forme d'un couple type / status. L'utilisateur pourra paramétrer sur intentPlatform la génération d'alertes en fonction des types et status qui seront transmis.

Ci-dessous un exemple d'alerting. Une alerte sera générée lorsqu'un type = ALARME PORTE BLOQUEE OUVERTE et un status = ANORMALE sera transmis. L'alerte se fermera lorsqu'un type = ALARME PORTE BLOQUEE OUVERTE et un status = NORMALE sera transmis sur intentPlatform.

https://slite.com/api/files/I4hMiI51G/Capture%20d%E2%80%99e%CC%81cran%202021-11-29%20a%CC%80%2011.04.27.png?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoicjFaX0NlTkMxayIsImlhdCI6MTcyOTA5MjA4NCwiaXNzIjoiaHR0cHM6Ly9zbGl0ZS5jb20iLCJqdGkiOiJlUElrdThDMVh2SU5LcyIsImV4cCI6MTczMTY4NDA4NH0.Z8KOBljoXJMz5Un1jAfGr9gJUs47yBQ54Z00P9KYyG0
Il est important d'avoir un événement "début" et "fin" pour chaque type d'événement afin qu'une alerte puisse être ouverte puis fermée.

Combien de flux vais-je créer ?

Dans le cadre d’un objet connecté signalant plusieurs événements ou du signalement humain de plusieurs événements sur un même équipement, nous recommandons la création d’un flux de données par activités d'événements, et non d’un flux de données par type d'événement.

Prenons l’exemple d’une chaudière individuelle qui est capable d’envoyer 4 types d’évènements :
    .1Activation - Arrêt de la chaudière (activité : SystemActivation)
    .2Panne de la chaudière (activité : SystemFailure)
    .3Défaut brûleur (activité : AlarmReport)
    .4Défaut électrique (activité : AlarmReport)
    .5Défaut connectivité (activité : AlarmReport)

Pour les 5 événements suivants, nous avons 3 familles d’activités. Nous recommandons donc la création de 3 flux de données. Nous aurons un même flux de données qui contiendra les événements 3, 4 et 5 d'une chaudière.
Par contre, la valeur dans le champ type devra être différente pour l’événement 3, 4 et 5. Si vous n’avez pas la possibilité de distinguer le type pour ces 2 événements, il faudra alors créer 3 flux de données.

Prenons l’exemple d’un ascenseur qui est capable de nous envoyer 4 types d’événements pour les mises à l’arrêt :
    .1Maintenance (activité : LiftState)
    .2Travaux (activité : LiftState)
    .3Panne (activité : LiftState)
    .4Mise à l’arrêt (activité : LiftState)

Pour les 4 événements suivants, nous avons 1 famille d’activité, santé ascenseur LiftState. 1 unique flux par ascenseur sera créé et il pourra recevoir 4 types différents.
Si vous avez des interrogations, le service client d’Intent Technologies vous accompagnera pour définir le bon nombre de flux à créer en fonction de vos usages ( cf. informations à transmettre ).

Création d'un stream événements par API

La 1ère étape avant tout envoi de données est la création d’un stream (flux de données).

Requête

 API data v1.0 
POST api/data/v1/streams

Paramètres

Un flux d'événements a toujours un type events et le champ intent_dataType alert.
Title
Title
Title
Description
champ
valeur
Référence du stream
reference
vous êtes libre de fixer la référence de votre choix.
Type du stream
type
events
Type de données
intent_dataType
alert
Référence de patrimoine lié
intent_assetReference
Référence du client
Référence du contrat lié
intent_contractReference
Votre référence de contrat
Libellé du flux
label
Description
description
Activités
intent_activityKey
 Liste des activités disponibles  
tag libre
tag
La référence ne peut pas contenir de "/"

Nous déconseillons l'utilisation de caractères spéciaux (@;#;&;^;*,etc.) et d'espace.
La référence d'un stream doit être unique pour toute votre entité sur intentPlatform.

Pour les flux de type events, les activités recommandées sont :
  • LiftState, AlarmReport, HealthState, SystemFailure, SystemActivation, BatteryLevel

Publication de données sur un stream de type events

Une fois que les streams ont été créés, vous pouvez envoyer vos données par API.

Requête

 API data v1.0 
POST api/data/v1/events

Envoi des données via API

Lors de l’envoi de données 3 paramètres sont importants:
  • type : code permettant de déterminer la nature de l'alerte, par exemple : "PANNE" ou "Fuite d'eau" ou "Dépassement seuil"
  • status : statut de l'alerte, par exemple "DEBUT / FIN" ou "Haut / Normal / Bas" ou "HS / OK"
  • timestamp : marqueur temporel de l'alerte, au format  Unix timestamps (milliseconds) .
📘 Pensez aux utilisateurs
Les valeurs renseignées dans les champs type et status sont visibles des utilisateurs sur le web et le mobile sans traduction.
Il est donc important de penser à l'expérience utilisateur en indiquant des valeurs ayant un sens métier et compréhensible par tout profil d'utilisateur (gardien(ne), locataire, responsable d'agence, centre d'appel, expert technique)

Type et statuts recommandés

Ascenseur

Title
Title
Title
Title
Alertes
Activités
Type
Status
Maintenance
LiftState
Maintenance
DEBUT
FIN
Travaux
LiftState
Travaux
DEBUT
FIN
Panne
LiftState
Panne
DEBUT
FIN

VMC

Title
Title
Title
Title
Alertes
Activités
Type
Status
Seuil haut pression
AlarmReport
Pression haute
CRITIQUE
ANORMALE
NORMALE
Seuil bas pression
AlarmReport
Pression basse
CRITIQUE
ANORMALE
NORMALE
Alimentation
AlarmReport
Alimentation VMC
NORMALE
HS
Panne du caisson
SystemFailure
Panne
DEBUT
FIN

Capteur

Title
Title
Title
Title
Alertes
Activités
Type
Status
Etat de santé du capteur
HealthState
Etat de santé
HS
VARIABLE
OK
Niveau de batterie du capteur
BatteryLevel
Batterie
HS
FAIBLE
OK

Skydome

Title
Title
Title
Title
Alertes
Activités
Type
Status
Position du skydome
AlarmReport
Position
OUVERT
FERME

Pompe de relevage

Title
Title
Title
Title
Alertes
Activités
Type
Status
Panne d'une pompe
SystemFailure
Panne
DEBUT
FIN
Défaut alimentation électrique
AlarmReport
Panne
DEBUT
FIN
Dépassement niveau haut de la cuve
AlarmReport
Niveau
DÉBORDEMENT
HAUT
OK