Reports

Introduction

The Open Source Portfolio toolset includes a "Report" tool that may have broad application, whether or not the Sakai instance is using the other portfolio tools. Its purpose is to run predefined SQL-based queries against the Sakai database, store the results for later viewing and display the results in the browser window. Since it the SQL queries may be run against any tables in the Sakai database, this tool may be of interest to and number of Sakai user roles.

The Report tool may be added to a worksite using the "Worksite Setup", "Site Info" or "Sites" (where it known as "osp.reports") tool. The tool is packaged as part of the Open Source Portfolio tools, so you will need to ensure that those tools are "unstealthed" in sakai.properties if you intend to allow users that do not have access to the "Sites" tool to add it to a worksite.
To run a report there are a few step that need to be followed.

Conceptual Model

The OSP Report tool can run predefined SQL reports that are stored in a "Report Definition" file. The Report Definitions are read in during the startup of Sakai and changing them requires a restart of the Sakai server. Each report definition may contain placeholders for parameter values that can be entered by user running the report using the web interface.

When a report is run, the query engine creates a SQL query from the report definition and the user entered parameter values and run it against the Sakai database. The result of the query is an XML file containing the parameter values input and the result set in XML format. The set of parameter values may be saved as a "live report" that can be run again upon request. The results of any report may be saved for later viewing as a "snapshot".

Depending on how the report was defined in the definition file, multiple views of the result set may be available. The Report tool renders an HTML view of XML result sets from the view template selected.

The workflow through the tool supports the conceptual model and can be seen in figure 2.

Figure 1 - Conceptual model for the OSP Reports tool.

Figure 2 - Workflow through the Report tool.

Running Reports

When the report tool is opened, the user is presented with two types of information (see figure 3). The top half of the tool shows the reports available to be run (as defined in the report definition file at system startup). The bottom half of the tool shows the report results that have been saved and are available for viewing.

Figure 3 - The Report tool interface (Main Screen)

To run a report, select and click on one of the available report titles on the top half of the tool. The tool will prompt you to provide:

a Title for the report - You should choose a name indicative of the type of report and parameters you plan to enter.
whether or not the report will be a "Live Report" - Check this box if you want the report to be available to be run again with the same parameters.
Report Keywords - at this point, this feature is unused and can be disregarded.
a report Description - You can enter any information you want here.

Enter the required information and click the "Continue" button at the bottom of the screen to continue to the "Edit Report Parameters" screen. This screen will prompt you to enter values that will be used to generate the report results. Fill out the form with the values that you want to run the query with and click the "Generate Report Results" button at the bottom of the screen to run the query.

The Report Results screen shows the results of the query run with your parameter values. If the report definition specifies more than one view of the result, the dropdown menu will allow you to select alternative view(s). To change the view, select an alternative and click the "Change View" button.

Saving Reports

You can save the report results from the result view screen. If you want to save the result set for later viewing, click the "Save Snapshot" link on the menu bar at the top of the tool and click "Save Results" on the subsequent page. You will be returned back to the result view screen after a successful result save.

If the report was created as a "live" report and you are satisfied with the report, you may click the "Save Live Report" link on the menu bar at the top of the tool. A message will appear on the top of the tool to indicate a successful save of the report.

Report snapshots and saved live reports will appear on the main page of the tool as a selection in the lower half of the page.

Figure 4 - Report Results View Page

old documentation, left for reference

preparation

You need to add the quartz scheduler to one of your sites.
Go into Sites under the Admin worksite.
Add a new page and select the Quartz scheduler from the list of tools.

instructions

First there needs to be a matrix.
Then, preferably, be data for some users in a matrix.
Once the data is there, you need to run the quartz scheduler task for the data warehouse.
To do this you need to have the quartz tool installed in your tool bar.
You need to add the data warehouse task and then you need to set a trigger.
Setting the trigger to a minute or so ahead of "now."
There may be differences in the clock between the server and your computer so you may want two minutes.
Once the trigger is run, you can then go into the report manager and run a report with data.
(it may be hard to tell if or when the task is run)

Every time you change the data in the matrix is changed you need to rerun the data warehouse task. You also need to rerun the task every time tomcat is restarted.