Setting Up Analytics

The Wedia Analytics module is based on the Elastic engine and allows analyses of real-time data.

Prerequisites and installation

The storage and request of the events of the application is ensured by an Elastic server .

It will therefore be necessary to have a Elastic server in order to be able to store and view these statistics.

In addition to storage in Elastic all events are logged in a log file located in the administrative directories of Wedia and allow you to replay events if necessary.

Elastic Server Installation

Please always install the latest version on Elastic and start it to enable Wedia → Elastic connexion.

The ElasticSearch instance can be deployed locally on the Wedia server or on any other server accessible by the Wedia server. It is also possible and advised in production to deploy an entire ElasticSearch cluster.

You will find more information on installation and configuration of Elastic on their official documentation.

Caution

Prior versions to version 5.x and 6.x of Elastic are not supported.

Version 8.x is not yet supported.

Once the Elastic server is started, go to the system settings of Wedia /admin/ebnAdministration.ebn and to enter the setup information of one of the Elastic servers.

You will need to set up a “prefix” that will be added before all your index on the Elastic server to segregate multiple Wedia servers running on one Elastic server.

How do the analytics work ?

When an event occurs in the DAM, or an external system to the DAM, an API is called to record the event in a log.

The log is then :

enriched with metadata of the asset and the user
ingested to a dedicated index in Elastic.

The system can have multiple configurations :

technical events,
DAM related events,
monitoring events.

A configuration can be defined as an entry point in the analytic system for storing events.

A configuration is always constituted of :

a configuration name,
series of events.

Events are made up of:

a timestamp
a set of parameters defined by the system known as contextual parameters and are common to all events.
a set of event-specific parameters

Multiple dashboards are linked to these configurations :

The Analytics Dashboards are only available to Back-Office users.

DAM Dashboards are offered to DAM Administrators, as a way to understand how the DAM is used, and ship out of the box. Limited customization is possible, by adding additional metadata that will act as filters.
System Dashboards are offered to System Administrators, as a way to understand how the system performs technically. System Dashboards can be customized by coding new dashboards in additional Java Server Pages to monitor very specific events.

The analytics can also be queried through a REST API, or a ODATA API, to connect the analytics as a datasource to third party systems.

DAM Dashboards

The Wedia system ships with out of the box predefined DAM Dashboards, that fit most of the needs for our clients.

The entry point URL of DAM Dashboard is always /wcm.jspz?form_action=stats

The end-user documentation for the DAM Dashboards are available here : https://crossmedia.atlassian.net/wiki/spaces/WD/pages/1936949258

Theses dashboards are preset out of the box with any version >= 2021.3.0 .

They can be customized by adding addition filters that are unique to a client.

These filters appear with a “plus” icon in the dashboards :

These filters can be added on :

events specific to a DAM asset
events specific to a user

Example of a filter for a DAM asset :

in yellow, the additional filters set for filtering users, in green, the additional filters set for assets.

Please note that the filters will only appear in a dashboard if they are relevant : in the connexion tab for example, only filters related to the user will appear, as assets are not involved in the connexion process.

In order to add extra filter, you need to go the Admin, Structure mode, and add the following tag to the structure that will provide the list of filter values :

Keep in mind that only properties on the “user” object, and on the different “dam” objects, such as “asset” can be tagged. All other objects tagging will be ignored.

The tagging will take effect at the date on which the object is tagged : if you need to go backward in time, you will need to ask Wedia to :

delete your current analytics indexes
replay the ingestion of the previous data logs after these new properties have been tagged in the structure mode.

Analytics at the Asset level

Since version 2022.1.0 , similar dashboards are available at the asset level :

When relevant, addition filters will also show up in these dashboards :

Ingesting MediaDelivery data

When you are publishing your images on external website, you may analyze how they perform using the dedicated “Asset Distribution Dashboard” :

In this dashboard, extra analytics appear as table below the “hit graph” :

In our example, images taken by photographer “Aaron Burden” had 8 159 impressions on websites. Images tagged by the AI metadata “outdoor” has 18 267 impressions on websites.

An impression / hit means that the image was displayed on a website, in any resolution : thumbnail, large, original size. Sometime it could be in the results list, as a thumbnail, so it does not correlate with people actively “looking at” the asset.

Since 2021.2, a new “view” event has been introduced that is only used in the Portal / Back-office context, where the user look a a page describing the asset details.

To include the hits coming from external websites, protected through our CDN, it is necessary to ingest and process these CDN logs. This is important to activate a dedicated plugin, CDN_TO_ANALYTICS :

Please contact our Wedia Account manager to setup this plugin.

If you rewrite your image URLs for your website, we will need to understand how to pick the unique image identifier so that we can relate the hit with an asset in the DAM database.

Pushing events to the Analytics system

When needed, you may want to push specific events to the analytics system using our REST API: for example, you have set up a custom content picker based on your own technology, and need to count downloads that occur on your interface.

Wedia provides an API for that: https://club-wed.wedia-group.com/api/wedia/analytics/?export=redoc

Reading events from the Analytics system

Wedia provides a REST API to query the event datababse :

https://club-wed.wedia-group.com/api/wedia/analytics/?export=redoc

Connecting to a external datasource using oData

Wedia offers a standard connector for using the raw Analytics data in third party solutions supporting the oData exchange standard, such as Microsoft Excel, PowerBI, Tableau…

This is documented in this section : https://crossmedia.atlassian.net/wiki/spaces/WD/pages/2290778117

System Dashboards

These system dashboards provide dashboards for all configurations that exist in the system, mostly of technical nature.

System dashboards can be viewed via the analytics action of the back-office at the URL /wcm.jspz?form_action=analytics.

The buttons bar acts as a tab to allow the navigation between the different dashboards.

Clicking on the date allows you to access the calendars that allow you to set the date of the analysis timespan.

Statistics are always displayed over a period of time. The default timespan is 30 days.

Data vizualisation of system dashboards

Statistics data can be viewed in several ways according to requirements via graphic components:

as histograms allowing to visualize the events of events over a given period at fixed time intervals. For example, see the number of daily connections for the current month.
as allocations allowing to visualize groupings of events over the period according to a given criteria. For example, view the different languages of the users' logon over the period. These distributions can be represented as pie charts, graphs in columns or tables.
as counters allowing to visualize a number relative to the events over the period. For example, the number of different users over the period.
as tables allowing to visualize events such as that they were recorded in the system.

Histograms

These graphs can be used to represent the events as they have occurred over a given period of time at regular intervals.

This histogram shows the DAM activity on the month of January 2019.

The time interval here is one day. Each column represents all the events that happened every single day.

Interactions with the graphical component

Clicking on a column will adjust the viewing period from the dashboard to the period represented by the column.

It is also possible to select a time range directly on the graph by clicking on the graph and moving the mouse. The highlighted area will represent the new time period.

Whichever method is used, the new time period will then be updated and the dashboard will be redesigned by taking into account only the events that occurred during this period.

Data distributions

These graphs are used to represent distributions of data in events recorded in system configurations.

For example, if you want to visualize the distribution of connections by role to the system it will be possible to choose the representation by this type of graph by displaying the result as a pie chart.

The distribution graphs can be presented in different forms.

Pies

Columns

Tables

If it is present, the user will be able to change the representation mode (pie|column|table) by choosing the display mode that corresponds to him most in the dropdown list.

Interactions with graphical components

The components are interactive and it is possible to click on the results to add filters to all dashboard graphics components. As previously seen on the histogram graph where clicking on a column allows you to refine the results period, here clicking on an element allows you to add an event filter.

By clicking on the Download of the action pie for example (or column Download on the graph in columns or line Download of the table), the dashboard will be automatically updated by displaying only events related to the Download action.

Clicking on the label in the legend will exclude results events.

It is possible to combine filters by clicking on the results of a graphical element then by clicking on the results of another graphical component. Filters will be combined to each other.

Active filters are displayed at the top-left side of the screen.

Simple values

This component displays a simple event counter. It is possible to count either the total number of events according to a criteria over a given period of time or the number of separate events on the same criteria.

For example, the first can be used to count the total number of connections on the system, the second can count the number of different users who have logged on the application.

Designing a new System Dashboard.

When necessary, it is possible to add a new system dashboard page as a JSP page that will describe the graphs in that page.

These JSP pages should be placed into : bov3/analytics/content/dashboards

This sample code shows how to add a web-to-print dedicated dashboard that looks like :

<%@page import="wsnoheto.log.analytics.dashboards.Configurations"%>
<%@page import="wsnoheto.log.analytics.dashboards.SysW2pTemplateConfiguration"%>
<%@page pageEncoding="ISO-8859-15"  import="java.util.*,wsnoheto.engine.*"%>
<%@taglib prefix="c" uri="/WEB-INF/c.tld" %>
<%@taglib prefix="noheto" uri="/WEB-INF/noheto.tld" %>
<noheto:skipPage test="${noheto:isNotIncluded(pageContext.request)}"/>

<div class="dashboardContainer">
	<!-- Tous les graphiques apparaitront ici -->
</div>

<%
	Set<wsnoheto.log.analytics.EventsLogger.ExtraParam> extraParamNames = new HashSet();
	try {
		for(String objectname:Arrays.asList( "monodocmodel" , "zsnippet" )) {
			extraParamNames.addAll(wsnoheto.log.analytics.EventsLogger.geSysObjectDataEventExtras(objectname));	
		}
	} catch (Throwable e) {
		// tant pis
	}
	pageContext.setAttribute("extraParamNames", extraParamNames);
	pageContext.setAttribute("extraSurferParamNames", wsnoheto.log.analytics.EventsLogger.getEventSurferExtras());

%>
<%
	SysW2pTemplateConfiguration dashboard_config = Configurations.load().getSysW2pTemplateConfiguration();
%>

<script type="text/javascript">
	/*
	context courant
	*/
	var configurationName="sys_objectdata";
	
	function createSearchOption() {
		var search_option = Analytics.SearchOption()
			.setConfigurationName(configurationName)
			//.putSort( Analytics.FieldSort("@timestamp",false) ) sinon pas de cache
			.setSize(0); // si !=0 alors pas de cache
		search_option.getQuery()
			.mustIn("event.params.objectname", ["monodocmodel","zsnippet"])
		;
		return search_option;
	}
	
	$(document).ready(function () {
		var dashboardname = "sys_w2p_template";
		
		BOV3AnalyticsHelper.addHistogram({
			fieldname:"@timestamp",
			label:boi18n.getMessage( "/bov3/wcm", "analytics.dashboard."+ dashboardname + ".chart.histogram" + ".aggregationlabel" ),
			title:boi18n.getMessage( "/bov3/wcm", "analytics.dashboard."+ dashboardname + ".chart.histogram" + ".title" )
			,classHeight:"analytics-grid-bloc_height_full"

			,subAggs:[
				null
				<% if (dashboard_config.isTermsParamsActionIdViewable()) { %>
				, {name:"event.params.actionid",fieldname:"event.params.actionid",method:Analytics.TermsAggregation,aggregationOptions:{stacked:true,visible:false}}
				<% } %>
				<% if (dashboard_config.isTermsParamsObjectNameViewable()) { %>
				, {name:"event.params.objectname",fieldname:"event.params.objectname",method:Analytics.TermsAggregation,aggregationOptions:{stacked:true,visible:false}}
				<% } %>
			<%--
            , {name:"event.params.damobject_type",fieldname:"event.params.damobject_type",method:Analytics.TermsAggregation,aggregationOptions:{stacked:true,visible:false}}
            , {name:"event.context.session.type",fieldname:"event.context.session.type",method:Analytics.TermsAggregation,aggregationOptions:{stacked:true,visible:false}}
            , {name:"event.params.statusuid",fieldname:"event.params.statusuid",method:Analytics.TermsAggregation,aggregationOptions:{stacked:true,visible:false}}

            <c:forEach items="${extraSurferParamNames}" var="extraSurferParamName">
                ,{
                    name:"event.context.surfer.extra.${noheto:escapeXml(extraSurferParamName.getAnalyticsShortname())}",
                    fieldname:"event.context.surfer.extra.${noheto:escapeXml(extraSurferParamName.getAnalyticsShortname())}",
                    method:Analytics.TermsAggregation,
                    aggregationOptions: {
                        visible:false,
                        stacked:true,
                        label:boi18n.getMessage( "/bov3/wcm", "analytics.dashboard.surfer" )+ " <noheto:str value='${noheto:i18nObjectField(wcmFieldnameBundle, extraSurferParamName.getField())}' escapeXml='false'/>"
                    }
                }
            </c:forEach>
            <c:forEach items="${extraParamNames}" var="extraParamName">
                ,{
                    name:"event.params.${noheto:escapeXml(extraParamName.getAnalyticsShortname())}",
                    fieldname:"event.params.${noheto:escapeXml(extraParamName.getAnalyticsShortname())}",
                    method:Analytics.TermsAggregation,
                    aggregationOptions: {
                        visible:false,
                        stacked:true,
                        label:"<noheto:str value='${noheto:i18nObjectField(wcmFieldnameBundle, extraParamName.getField())}' escapeXml='false'/>"
                    }
                }
            </c:forEach>
            --%>
        ]

		});

		<%
			dashboard_config.draw(pageContext, extraParamNames);
		%>

		Analytics.Manager().refresh();
	});
</script>