Ces configurations permettent de mettre en place programmatiquement au sein d’un projet des indicateurs spécifiques qui permettront de réaliser des analyses statistiques dédiées à une application et qui ne seraient pas couvertes par les configurations systèmes livrées en standard.
L’écran /admin/analytics permet de consulter l’ensemble des configurations existantes dans le système (applicative et système). Depuis cet écran il est possible de créer et documenter de nouvelles configurations.
Note | Un événement n’a pas besoin que sa configuration ait été préalablement créée via cet écran. Si la configuration n’existe pas encore elle sera automatiquement créée par l’API de collecte des données lorsque l’événement se produira. |
Détail d’une configuration
Nom de la configuration
Le nom de la configuration permet de différencier les différentes configurations existantes dans le système et isoler les différents événements analysables.
Un nom doit nécessairement respecter les contraintes suivantes
le nom doit obligatoirement être en minuscule,
la longueur du nom ne doit pas dépasser 50 caractères,
le nom ne peut comporter que des lettres (a-z), des chiffres (0-9) ou les espaceurs suivants
-ou_le nom ne peut pas commencer ou terminer par un espaceur.(
-ou_)
Paramètres de l’événement
Ces paramètres sont définis par le développeur et peuvent être très variés. Ils sont généralement définis afin de répondre à un besoin d’analyse précis. On peut par exemple y trouver des noms d’actions, des noms d’objets et d’identifiants, des uid, des codes retours, etc …
Le nombre de paramètres utilisateurs n’est pas limité; toutefois il est prudent d’éviter d’enregistrer des paramètres qui pourraient ne jamais servir.
Ces paramètres viendront s’ajouter aux paramètres contextuels stockés automatiquement par le moteur.
Noms des paramètres
Comme les noms de configurations, les noms des paramètres doivent respecter les contraintes suivantes :
le nom doit être en minuscule,
la longueur du nom ne doit pas dépasser 20 caractères,
le nom ne peut comporter que des lettres (a-z), des chiffres (0-9) ou les espaceurs suivants
-ou_le nom ne peut pas commencer ou terminer par un espaceur.(
-ou_)
objectname
objectid
actionname
Valeurs des paramètres
Les valeurs des paramètres peuvent être de natures suivantes : String, Long ou Boolean.
Il est très important de toujours stocker la valeur d’un paramètre avec le même type sans quoi il ne sera pas possible de réaliser des analyses statistiques fiables sur ces paramètres.
Accès aux paramètres applicatifs
Dans la construction des dashboards on pourra se servir des paramètres applicatifs pour filtrer des données dans une option de recherche ou comme donnée à représenter à l’utilisateur. Les paramètres applicatifs sont tous stockés sous la clef event.params.
Si l’on souhaite récupérer une des variables, on y accèdera via sa clef event.params.NOM_VARIABLE, par exemple event.params.actionname pour le paramètre applicatif actionname.
Configuration details
These configurations will help developers to build custom dashboards for their projects.
Developers will be able to programmatically log events with their own parameters and build dashboards over those configurations.
Custom loggers are defined with name (unique on the system) and parameters.
Configuration name
The configuration name is used to differentiate the different configurations and isolate the various analysable events.
A name must respect the following constraints
the name must be in lower case,
the length of the name must not exceed 30 characters,
the name can only contain letters (a-z) and numbers (0-9) or the following spacers
-or_.the name cannot starts or end with a spacer.
Tip | A configuration will store all the events related to it, it can be "seen" as a table in a database. |
Events parameters
These parameters are defined by the developer at development time.
They are generally defined to meet a specific analytical need.
You can for example find names of actions, names of objects and identifiers, uid, return codes, etc.
The number of user parameters is not limited; however, it is prudent to avoid saving parameters that may never be used.
These parameters will be added to the stored contextual parameters automatically by the engine.
Parameters are key/values entries represented in a java.util.Map<String,Object>
Parameter names
As with configuration names, parameter names must respect the following parameters the following constraints :
the name must be lowercased,
the length of the name must not exceed 30 characters,
the name can only contain letters (a-z), numbers (0-9) or the following spaces
-or_.the name can’t start or end with a spacer.
Example of a valid parameter name
objectname
objectid
actionname
Parameter values
Parameters values can use the following java types : String, Long, Boolean , List<String>
It is very important to always store the value of a parameter with the same type, otherwise it will not be possible to carry out analyses reliable statistics with these parameters.
Application parameters
Application parameters are all stored under the event.params key and can be accessed with their keynames event.params.VARIABLE_NAME, e.g. event.params.actionname for the application parameter actionname.
Parameters may be used as search filters when building dashboards.
connexion_search_option.getQuery()
.mustEquals("event.params.actionname", "download");connexion_search_option.putAggregation( "cardinality", Analytics.CardinalityAggregation("event.params.actionname") );Production d’événements
L’ajout de nouveaux événements dans le système se fait via l’unique point d’entrée situé dans les APIs Analytics dans la classeEvent generation
The addition of new events in the system is done via the unique entry point located in Analytics APIs in the wsnoheto.log.analytics.EventsLogger class.
Les méthodes The EventsLogger.logEvent et and EventsLogger.logSysObjectDataEvent permettront d’enregistrer toutes les productions d’événements applicatifs methods will record all the productions of application events.
- EventsLogger.logEvent
Permet de créer un nouvel événement dans une configuration applicative,Allows you to create a new event in an application configuration
- EventsLogger.logSysObjectDataEvent
Permet de créer un nouvel événement dans la configuration
sys_objectdataafin d’alimenter la configuration système avec des événements ayant lieu hors du périmètre d’application standard (back-office standard).
Par exemple sur un front-office custom on pourra souhaiter notifier la configurationsys_objectdatalorsqu’un utilisateur consulte la fiche d’un asset.
Allows to create a new event in the
sys_objectdataconfiguration in order to feed the system configuration with events taking place outside the standard scope of application (standard back-office).
For example, on a customised front-office we may wish to notify thesys_objectdataconfiguration when a user consults the asset detail.
Tip | See the javadoc of the class wsnoheto.log.analytics.EventsLogger pour plus d’informationsfor more information. |
Event production via EventsLogger.logEvent
C’est la méthode la plus à utiliser pour enregistrer des événements applicatifs dans le système. Cette méthode prend les paramètres suivants This is the most common way to record application events in the system.
This method takes the following parameters:
- <wsnoheto.engine.CTSurfer> surfer
Le surfer réalisant l’action et permettant d’alimenter les paramètres contextuels de l’événement - bien qu’il puisse être null il est très fortement conseillé de le renseignerThe connected user performing the action and allowing to feed the contextual parameters of the event - although it can be null it is highly recommended to inform him/her.
- <String> configuration_name
Le nom de la configuration applicative dans laquelle l’événement sera enregistré. Ce paramètre est obligatoire et ne peut être ni null ni videThe name of the application configuration in which the event will be saved. This parameter is mandatory and cannot be null or empty.
- <java.util.Map<String, Object>> params
Les paramètres de l’événement représentés par une The event parameters represented by a
java.util.Map<String, Object>. Ce paramètre ne peut être This parameter cannot be null.
Map<String, Object> myParameters = new HashMap<String, Object>();
myParameters.put( "actionname" , "action1" );
myParameters.put( "param2" , "value2" );
myParameters.put( "param3" , false );
myParameters.put( "param4" , 15 );
EventsLogger.logEvent(CTSurfer.from(request), "myConfiguration", myParameters );Note | L’appel de la méthode logEvent est suffisant pour créer l’événement dans le système ainsi que sa configuration applicative (myConfiguration) si elle n’existe pas déjà. |
Création d’événement via EventsLogger.logSysObjectDataEvent
Cette méthode permet de créer un nouvel événement dans la configuration système sys_objectdata.
Le seul paramètre d’événement qu’il est possible de régler est le paramètre actionid. Ce paramètre peut prendre une valeur non vide strictement différente de delete, update ou insert.
Elle permet par exemple d’enregistrer dans la configuration sys_objectdata des événements qui concernant la vie de objet mais pour lesquels on n’a pas nécessairement besoin de déclarer une nouvelle configuration comme la visualisation d’un objet (sur un front office), le téléchargement d’un asset (dans un panier), etc …
Cette méthode permet de couvrir des fonctionnalités existantes dans le back-office en dehors du contexte de ce dernier ou dans des plugins applicatifs tiers.
Par exemple on souhaite pouvoir enregistrer les appels à l’actionid view sur un front-office DAM lorsque l’utilisateur visionne une ressource d’un objet DAM. L’application système n’ayant pas connaissance des points d’entrées front, le développeur pourra alors invoquer l’enregistrement de l’action concernée depuis son Front DAM.
The logEvent method call is enough to create the event in the system and its application configuration (myConfiguration) if it doesn’t already exist. |
Event creation via EventsLogger.logSysObjectDataEvent
This method allows you to create a new event in the configuration system sys_objectdata.
The only event parameter that can be set is the actionid parameter. This parameter can take a non-empty value strictly different from delete, update or insert.
It allows for example to save in the sys_objectdata configuration events which concern the life of an object but for which one does not have necessarily need to declare a new configuration like the visualization of an object (on a front office), downloading an asset (in a basket), etc
This method can be used to cover existing functionalities in the back-office outside the context of the latter or in plugins third-party applications.
For example we want to be able to record the calls to actionid view on a DAM front-office when the user is viewing a resource of a DAM object. The system application has no knowledge of the front entry points, the developer will then be able to invoke the registration of the action concerned from his DAM Front.
// activeObject being the current object that the user consults.
EventsLogger.logSysObjectDataEvent(CTSurfer.from(request), "view", activeObject);Bonnes pratiques
Logger une valeur vide ou nulle
Lorsque l’on veut enregistrer une valeur vide ou nulle dans un des paramètres applicatif il est recommandé d’enregistrer le caractère - au lieu de ne rien mettre. Cela permet entre autre de pouvoir aisément réaliser des filtres dans les dashboards par la suite et facilite l’écriture des requêtes.
Logger la valeur une propriété child
Lorsque l’on veut enregistrer la valeur d’une propriété de type child dans un paramètre applicatif il est recommandé de logguer la valeur de l’UID de l’instance plutôt que de logger l’identifiant de l’instance ou la valeur d’une des propriétés de l’instance liée.
Par ailleurs on prendra soin de nommer le paramètre de manière à ce qu’il se termine par la chaîne de caractère uid. Lorsque le nom d’un paramètre se termine par uid alors les composants graphiques des dashboard iront chercher dans l’instance représentée par l’uid stocké la valeur internationnalisée de la propriété name de cette instance.
Par exemple si l’on veut stocker l’identifiant ID=18 dans un paramètre représentant le rôle de l’utilisateur alors
on nommera le paramètre de la manière suivante
leparametre_uidon stockera la valeur
role_18
Good practices
Log an empty or zero value
When you want to save an empty or zero value in one of the parameters application it is recommended to save the character - instead of not logging anything. This makes it possible, among other things, to easily create filters in the dashboards later and makes it easy to write queries.
Logging a child property value
When you want to record the value of a child property type in an application parameter it is recommended to log the value of the instance’s UID instead of logging the instance identifier or the value of one of the properties of the related instance.
In addition, care will be taken to name the parameter in such a way that it is ends with the uid character string.
When the name of a parameter ends with uid then the components dashboard graphs will fetch in the instance represented by the stored uid the internationalized value of the 8th property of this instance.
For example, if you want to store the identifier ID=18 in a parameter representing the role of the user then
the parameter will be named as follows
parameterx_uid.we will store the value `role_18'.
Map<String, Object> myParameters = new HashMap<String, Object>();
myParameters.put( "actionname" , "monaction" );
myParameters.put( "param2" , "value2" );
myParameters.put( "param3" , "-" ); // paramètrefor null or ouempty videparameter, alors on enregistreuse -
myParameters.put( "param4_uid" , "role_18" ); // le role role uid of the user
myParameters.put( "param5_uid" , "asset_257" ); // l'asset uid
EventsLogger.logEvent(CTSurfer.from(request), "myConfiguration", myParameters );