Configuration Options

Table of Contents

1. Information

All the configuration keys referred on this page are optional and therefore are not required to startup Sakai with SiteStats. These keys should go in sakai.properties

Upgrading between major releases (0.5 -> 1.0 -> 2.0)

Please note that configuration keys in sakai.properties often changes between major releases. You need to review your configuration based on the information provided on this page. Starting Sakai with an invalid configuration will lead to a startup failure.

2. Site Stats configuration options

2.1. Default Overview/Report pages options

Configuration key	Description	Version	Default value
chartBackgroundColor@org.sakaiproject.sitestats.api.StatsManager	Default chart background color	1.0+	white
chartIn3D@org.sakaiproject.sitestats.api.StatsManager	Show charts in 3D by default? This is unused starting from 2.0 as most charts don't support this setting.	1.0+ (< 2.0)	false
chartTransparency@org.sakaiproject.sitestats.api.StatsManager	Default chart transparency (acceptable values: 0.10f - 1.00f, where 0.10f = 10% and 1.00f = 100%)	1.0+	1.00f
itemLabelsVisible@org.sakaiproject.sitestats.api.StatsManager	Show bar charts item labels by default?	1.0+	false
enableSiteVisits@org.sakaiproject.sitestats.api.StatsManager	Force the enable/disable of display visits related information in the tool	1.0.4+	Tool checks if presence is enabled/disabled or if 'presence.events.log' property is set in Sakai to determine default value
enableSiteActivity@org.sakaiproject.sitestats.api.StatsManager	Enable/disable the display of the activity chart in SiteStats Overview page.	1.0.2+	true
enableResourceStats@org.sakaiproject.sitestats.api.StatsManager	Enable/disable the display of Resource statistics in SiteStats Overview page.	2.0+	true
countFilesUsingCHS@org.sakaiproject.sitestats.api.StatsManager	Enable/disable the counting of files using ContentHostingService (enabling is more inefficient but more precise if files were added before SiteStats were added to a site (if events are only aggregated for sites with SiteStats added)).	2.0+	true in 2.1.0+ (was false, in 2.0.x). See STAT-203/STAT-205
enableSitePresences@org.sakaiproject.sitestats.api.StatsManager	Enable/disable of display site presence time related information in the tool. Also requires presence service enabled ('display.users.present=true'), otherwise feature will be disabled. Using 'presence.events.log=true' instead won't work because visits will always terminate after the value defined in 'timeoutSeconds@org.sakaiproject.presence.api.PresenceService' (seconds)	2.2.0+	false
sortUsersByDisplayName@org.sakaiproject.sitestats.api.StatsManager	Use "User.getDisplayName()" for user name display. Default changed to "User.getSortName()" in STAT-243 for consistency across Sakai tools.	2.2.0+	false

2.2. Event aggregation configuration options

Configuration key	Description	Version	Default value
collectThreadEnabled@org.sakaiproject.sitestats.api.StatsUpdateManager	Enable/disable collect thread	1.0+	true
collectThreadUpdateInterval@org.sakaiproject.sitestats.api.StatsUpdateManager	Db update interval for collect thread (in ms)	1.0+	4000
collectAdminEvents@org.sakaiproject.sitestats.api.StatsUpdateManager	Aggregate administrator events?	1.0+	false
collectEventsForSiteWithToolOnly@org.sakaiproject.sitestats.api.StatsUpdateManager	Aggregate events ONLY for sites with SiteStats tool?	1.0+	true
showAnonymousAccessEvents@org.sakaiproject.sitestats.api.StatsManager	Aggregate anonymous access events for public sites (with .anon role)	2.4.x 2.5.x 2.0+	true
lastJobRunDateVisible@org.sakaiproject.sitestats.api.StatsManager	Show/hide date from last event processed by the quartz job in tool overview page:	1.0+	true if collectThreadEnabled = false, false otherwise
maxEventsPerRun@org.sakaiproject.sitestats.api.StatsAggregateJob	Max # of events to be aggregated by the Quartz job	1.0+	50000
startEventId@org.sakaiproject.sitestats.api.StatsAggregateJob	First eventId to be processed by the Quartz job. If not specified, job will use the higher eventId available in SAKAI_EVENT when Sakai started up. This is for the first job run only - after that, status is maintained in SST_JOB_RUN table	1.0+	By default, will use the higher eventId available in SAKAI_EVENT when Sakai started up
driverClassName@org.sakaiproject.sitestats.api.StatsAggregateJob	DB driver class name. Use this if SAKAI_EVENT and SAKAI_SESSION lives on a different database from the Sakai one	1.0+	none
url@org.sakaiproject.sitestats.api.StatsAggregateJob	Jdbc url for the alternative database. Use this if SAKAI_EVENT and SAKAI_SESSION lives on a different database from the Sakai one	1.0+	none
username@org.sakaiproject.sitestats.api.StatsAggregateJob	Username for accessing the alternative database. Use this if SAKAI_EVENT and SAKAI_SESSION lives on a different database from the Sakai one	1.0+	none
password@org.sakaiproject.sitestats.api.StatsAggregateJob	Password for accessing the alternative database. Use this if SAKAI_EVENT and SAKAI_SESSION lives on a different database from the Sakai one	1.0+	none

2.3. Tool/event support (add/remove)

Generated events may differ between Sakai releases

SiteStats have different event definition files for different Sakai releases. You may want to point * toolEventsDefinitionFile* setting below to the appropriate file in your installation (view folder content). A filename without version number means it is for the current sakai release.

Configuration key	Description	Version	Default value
toolEventsAddDefinitionFile@org.sakaiproject.sitestats.api.StatsUpdateManager	Path to tool event definition file: add support for new tools or new events to existing tools. Can also be used to change default selected flag.	1.x	n.a.
toolEventsRemoveDefinitionFile@org.sakaiproject.sitestats.api.StatsUpdateManager	Path to tool event definition file: remove support for entire Tools or subset of Tool events.	1.x	n.a.
toolEventsDefinitionFile@org.sakaiproject.sitestats.api.StatsUpdateManager	Path to tool event definition file (events to be collected). This will completely replace the default bundled definition file.	1.x	toolEventsDef.xml
toolEventsAddDefinitionFile@org.sakaiproject.sitestats.api.event.FileEventRegistry	Path to tool event definition file: add support for new tools or new events to existing tools. Can also be used to change default selected flag.	2.0+	n.a.
toolEventsRemoveDefinitionFile@org.sakaiproject.sitestats.api.event.FileEventRegistry	Path to tool event definition file: remove support for entire Tools or subset of Tool events.	2.0+	n.a.
toolEventsDefinitionFile@org.sakaiproject.sitestats.api.event.FileEventRegistry	Path to tool event definition file (events to be collected). This will completely replace the default bundled definition file.	2.0+	toolEventsDef.xml
checkLocalEventNamesFirst@org.sakaiproject.sitestats.api.event.EntityBrokerEventRegistry	Whether to first check local event descriptions provided within the Site Stats bundles and, second, check event descriptions provided in Statisticable capability implementations. By default this is false (reverse order).	2.0+	false

Note: The recommendation here is to not replace the default bundled configuration file in order to get support for additional tools uppon SiteStats updates.

Warning

When adding new tool events, the event description must be specified in the appropriate resource bundle file located in:

(SiteStats >= 1.2) sitestats/sitestats-bundles/Events.properties
(SiteStats <= 1.1) sitestats/sitestats-impl/src/bundle/org/sakaiproject/sitestats/impl/bundle/Messages.properties

2.3.1 Tool event definition file (excerpt)

Below is an excerpt of the tool event definition file used by SiteStats.

<?xml version="1.0" encoding="UTF-8" ?>
<toolEventsDef>
	<!-- announcements -->
	<tool
		toolId="sakai.announcements"
		selected="true">
		<event eventId="annc.new" selected="true"/>
		<event eventId="annc.revise.own" selected="true"/>
		<event eventId="annc.revise.any" selected="true"/>
		<event eventId="annc.delete.own" selected="true"/>
		<event eventId="annc.delete.any" selected="true"/>
		<eventParserTip for="contextId" separator="/" index="3"/>
	</tool>
<!-- (...) -->
</toolEventsDef>

XML Fields Description

<TOOL>	A Sakai tool
tool – toolId	Sakai tool id
tool – selected	Selected by default?
<EVENT>	An event logged by the tool
tool – event – eventId	Logged event id
tool – event – selected	Selected by default?
<EVENTPARSERTIP>	Parsing tip of the REF field for contextId (site id)
tool – eventParserTip – for	Context id
tool – eventParserTip – separator	String separator
tool – eventParserTip – index	Index position

Example event reference for an Announcement logged event:
annc.new | /announcement/channel/~e65550f9-14c5-41ac-80be-a0657febd4ca/main

2.4. Enabling tracking of site visits

In Sakai 2.4.x / 2.5.x:
In order to be possible to track site visits in Sakai, the list of users present in site must be enabled (Sakai Presence service). If

Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.

is not applied into your sakai installation (most probable), the following configuration key is required in sakai.properties:

display.users.present = true

In Sakai trunk / 2.6+:
The list of users present in site is not a requirement anymore (see

SAK-8499 - Presence events are only logged if presence list is enabled Closed

) as long as the following configuration key is specified in sakai.properties:

presence.events.log = true

Common:
The tool will hide all visits related information if presence events are disabled in sakai.properties. However, you can force the enable/disable of visits related information in SiteStats:

Configuration key	Description	Default value
enableSiteVisits@org.sakaiproject.sitestats.api.StatsManager	Force the enable/disable of display visits related information in the tool	Tool checks if presence is enabled/disabled or if 'presence.events.log' property is set in Sakai to determine default value

2.5. External database configuration options

Version

This feature requires SiteStats version >= 1.2 or trunk.

Configuration key	Description	Version	Default value
sitestats.db	Whether to use internal Sakai database or external database (same or different server) for SiteStats tables. Possible values: internal, external	1.2+	internal
sitestats.externalDb.auto.ddl	Set whether to execute a schema update after SessionFactory initialization	1.2+	true
sitestats.externalDb.hibernate.dialect	Hibernate dialect for external db	1.2+	org.hibernate.dialect.HSQLDialect
driverClassName@org.sakaiproject.sitestats.externalDbDataSource	Fully qualified Java class name of the JDBC driver for external db	1.2+	org.hsqldb.jdbcDriver
url@org.sakaiproject.sitestats.externalDbDataSource	Connection URL to be passed to JDBC driver for external db connection	1.2+	jdbc:hsqldb:mem:sitestats_db
username@org.sakaiproject.sitestats.externalDbDataSource	Username for external db	1.2+	sa
password@org.sakaiproject.sitestats.externalDbDataSource	Password for external db	1.2+
sitestats.externalDb.name	Server wide stats require this additional setting so that they are able to query both the main Sakai database and the external Sitestats database. There are caveats though: The database must be on the same URL as the main Sakai database and the user for the main Sakai DB must have read access. Essentially, the two databases need to be side by side. See: Unable to locate Jira server for this macro. It may be due to Application Link configuration.	2.3.2+

By default, the datasource connection pool is configured as follows:

initialSize = 3
maxActive = 5
maxIdle = 3
minIdle = 3
timeBetweenEvictionRunsMillis = -1
More datasource options are available at the Apache Commons API javadocs page.

2.6. Predefined reports

Version

This feature requires SiteStats version >= 2.0 or trunk.

Predefined reports are available to all SiteStats tool instances (all sites). Users are allowed to run, edit before run, and duplicate to modify a local report copy (but are not allowed to modify the original predefined report). To add or modify existing predefined reports:

Either add SiteStats Admin tool to Administration Workspace or add it to some user My Workspace (in the later case, the user will also need to have the permission function sitestats.admin.view in his My Workspace);
Using SiteStats Admin tool, add and/or modify existing predefined reports as desired;
In order to have the report title and description in multiple languages (I18N), both must be added to the appropriate bundle files in sitestats/sitestats-bundles/Messages*.properties. The bundle keys are then added as title and description on the Report editing form (specified with syntax ${bundle_key}). Example:
```
#
# Predefined reports
#
predefined_report12_title = Activity total
predefined_report12_description = Show activity in site, with totals per event.
```
... and, on Report edit form, specify:
```
Title: ${predefined_report12_title}
Description: ${predefined_report12_description}
```
Warning

When adding or changing bundle files with localized predefined report titles and descriptions, SiteStats will need to be re-compiled and re-deployed (with Tomcat stopped)!

3. Other configuration options

3.1 Enabling tracking of Wiki page reads

3.1.1 On Sakai 2.6.x

Apply SAK-15026 - Issues with wiki read tracking Closed patch to your Sakai installation, re-compile and re-deploy (for your convenience: Rwiki_SAK-15026.patch)
Specify wiki.trackreads = true in sakai.properties

3.1.2 On Sakai 2.5.x

Depending on SAK-11214 - Allow enable/disable of wiki reads events through sakai.properties Closed resolution, you may need to either add a configuration key to sakai.properties or manually perform the following change:

open /rwiki-tool/tool/src/webapp/WEB-INF/commandComponents.xml
set property trackReads of bean uk.ac.cam.caret.sakai.rwiki.tool.service.api.CommandService to true
save the file and redeploy rwiki component