300 Custom Configurations

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 _)

Exemple de nom de paramètres valides

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.

Exemple d’utilisation d’un paramètre applicatif pour filtrer des résultats de recherche dans une option de recherche

connexion_search_option.getQuery().mustEquals("event.params.actionname", "actionvalue");

Exemple d’utilisation d’un paramètre applicatif pour la déclaration d’un comptage du nombre d’occurences différentes du paramètre actionname

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 classe wsnoheto.log.analytics.EventsLogger.

Les méthodes EventsLogger.logEvent et EventsLogger.logSysObjectDataEvent permettront d’enregistrer toutes les productions d’événements applicatifs.

EventsLogger.logEvent: Permet de créer un nouvel événement dans une configuration applicative,
EventsLogger.logSysObjectDataEvent: Permet de créer un nouvel événement dans la configuration sys_objectdata afin 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 configuration sys_objectdata lorsqu’un utilisateur consulte la fiche d’un asset.

Tip	Reportez-vous à la javadoc de la classe wsnoheto.log.analytics.EventsLogger pour plus d’informations.

Production d’événements 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 :

<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 renseigner
<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 vide.
<java.util.Map<String,Object>> params: Les paramètres de l’événement représentés par une java.util.Map<String,Object>. Ce paramètre ne peut être null.

Exemple de création d’événements dans une page JSP

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.

Exemple de création d’événements dans une page JSP

// activeObject étant l'objet courant que l'utilisateur consulte
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_uid
on stockera la valeur role_18

Exemple de création d’événements child dans une page JSP

Map<String, Object> myParameters = new HashMap<String, Object>();
myParameters.put( "actionname" , "monaction" );
myParameters.put( "param2" , "value2" );
myParameters.put( "param3" , "-" ); // paramètre null ou vide, alors on enregistre -
myParameters.put( "param4_uid" , "role_18" ); // le role
myParameters.put( "param5_uid" , "asset_257" ); // l'asset
EventsLogger.logEvent(CTSurfer.from(request), "myConfiguration", myParameters );