Event Report Tool Instructions¶
- Event Report Tool Instructions
This document aims to instruct how to use the Event Report tool (ERT) to merge GIFT event output files and create event reports. Events that occur during a domain session are stored in various places and formats (e.g., bookmark files, domain session log files), therefore the ERT was created to facilitate the selection and merging of important events from those sources. Once a report is configured, an output file can be created (e.g., csv) that can be imported into a third party tool (e.g., Excel, SPSS, RapidMiner, etc.) for further analysis.
Where to Start¶
Follow the instructions within the “Run Instructions” document to bring up the ERT Webpage.
Selecting Event Sources¶
Before you can begin to configure an ERT report, you must select the event source file(s). Figure 1 shows the select event source(s) page which is the first page that appears when the ERT is launched.
Figure 1. Screenshot of the ERT event source selection web page.
You can select more than one source file by holding the “Ctrl” button on your keyboard and then left mouse clicking on your selections.
When finished selecting one or more event sources, click the “Continue” button.
Configure and Create Report¶
After the event source(s) have been selected, a web page resembling the one shown in Figure 2 will be created. The top left list box is populated with all of the events found in the event source(s). Those event types listed for the ERT property value “defaultEventTypes” (in ert.properties) will be checked by default to facilitate quicker report generation (more information can be found here under Tool Properties – Event Report Tool section). From here you are free to customize the report that will be created as described in the following sections.
Figure 2. A screenshot of the ERT web page showing the events and event type columns for a selected domain session log.
Customize Event Type Columns¶
In order to specify which columns of a particular event type will be included in the report, select the “Customize” link and then check/uncheck each corresponding column that is listed in the list box to the right of the list of events. The event type columns list will contain the columns for every event of that type found in the event source(s). Keep in mind that if the event type is not selected, i.e., checked, the event type columns will not appear in the report even if they are checked themselves.
Customize Default Columns¶
The default columns are a list of columns that every row will have in the report (e.g. Time). These include metadata about the event such as various time stamps and the event type name. You can change the ordering of these columns by using the up/down arrow buttons. In addition, the columns can be removed or added from the report by selecting the checkbox next to each column name.
Some of the default columns such as “Time” have additional customization that can be selected. This includes filtering events out of a generated report based on a window of time. An example of this dialog is shown in Figure 2.
Exclude Empty Columns¶
Checking this property will remove any columns where all of its cells are empty. This can happen based on default column filter settings. For example, when a report would normally have a column with values in it but those values are then filtered out based on the filter parameters.
Sort By Column¶
The sort by column will order the rows in the generated report file by the value in each row for the column chosen (ascending order). Currently only the default columns (e.g. user id) are available as choices for sorting.
Merge By Column¶
The merge by column will combine rows where the values for the ‘merge-by-column’ match. Currently only the default columns (e.g. domain session id) are available as choices for merging.
There are several things to consider when merging rows (consider RowA being merged with RowB).
- If RowA and RowB have different, non-empty, values in any column (other than the merge-by-column), a new column will be added to the report with a suffix (e.g. (2) ) added to the column name. The new column name will have the value of RowB in it for the resulting row of merging RowA and RowB.
- If the merge-by-column is a time based column (e.g. time, domain session time), than all other time columns will be removed from the report.
- If the merge-by-column is not a time based column, than all of the time based columns will be removed from the report.
Empty Cell Value¶
Usually there will be empty cells in the report being generated due to the fact that events are time stamped down to the millisecond and every row in the report contains the columns for all events as configured by the user. For this reason, the ERT allows you to provide the value that will be written to the report file in place of no data (i.e. nothing). This is useful for third party tools such as SPSS which requires a period (“.”) in empty cells.
Create Report Output File¶
After the report has been configured, select “Create File” and a file will be written to the GIFT output directory where the Admin Server is running (this is temporary, eventually an option for “File Save As…” dialog will be included allowing local file creation).
Use this feature to save the current report settings to a file that can be loaded in the future. The settings file will be written to the GIFT output directory where the Admin server is running (this is temporary, eventually an option for “File Save As…” dialog will be included allowing local file creation).
Use this feature to load the settings saved in a file. Currently, only the list of settings files located in the GIFT output directory where the Admin server is running (this is temporary, eventually an option for “File Save As…” dialog will be included allowing local file creation) will be shown for selection.
If a column is in the loaded settings file but is not in any of the event sources selected, than that column will be ignored. For example, if the settings file has a reference to a survey question column, however the selected event source(s) don’t have any survey events in them. In this example the survey question column will not be shown on the ERT customize report page.