Custom Configurations

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.
An event can be seen as a line in this configuration’s table.
A parameter can be seen as a column in the configuration’s table.

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.

Example using an application parameter to filter search results in a search option - this example will retrieve all events where actionname = 'download'

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

Example using an application parameter to report a count of the number of different occurrences from the actionname parameter.

connexion_search_option.putAggregation( "cardinality", Analytics.CardinalityAggregation("event.params.actionname") );

Event 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.

The EventsLogger.logEvent and EventsLogger.logSysObjectDataEvent methods will record all the productions of application events.

EventsLogger.logEvent

Allows you to create a new event in an application configuration

EventsLogger.logSysObjectDataEvent

Allows to create a new event in the sys_objectdata configuration 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 the sys_objectdata configuration when a user consults the asset detail.

Tip

See the javadoc of the class wsnoheto.log.analytics.EventsLogger for more information.

Event production via EventsLogger.logEvent

This is the most common way to record application events in the system.

This method takes the following parameters:

<wsnoheto.engine.CTSurfer> surfer

The 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

The 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

The event parameters represented by a java.util.Map<String, Object>. This parameter cannot be null.

Example of event creation in a JSP page

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

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.

Example of event creation in a JSP page

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'.

Example of creating child events in a JSP page