Upgrading
Here we will list instructions on how to upgrade existing xReporter installations from one xReporter version to the next.
Before upgrading, you may want to check what has been changed in between releases.
From version 1.2 or 1.2.1 to 1.2.2
To support public-saved-reports there has been a change to the xreporteradmin
database. For running configurations this means you should run the following
alter-table scrip:
(available as a separate file xreporteradmin_upd_1.2.1_1.2.2.mysql in
{XREPORTER_HOME}/src/resources/schema/dbschema/)
alter table reportstore add column
is_public TINYINT(1) not null default '0';
create index rs_public_idx on reportstore (is_public);
Also this and other changes introduce some new i18n messages and graphical
elements that you'ld want your personal skin and localization to be made aware
of.
If you have provided own translation files for the i18n resource at
{XREPORTER-COCOON}/src/resources/common/messages*.xml, then additional
translations should be made for these keys:
<message key="save-make-public">Make public</message>
<message key="no-publicsaved-reports">There are no publicly available saved reports.</message>
<message key="public-saved-reports">Publicly available saved reports.</message>
<message key="personal-saved-reports">Personal saved reports.</message>
<message key="other-saved-reports">Other saved reports</message>
<message key="togglepublic-stored-report">Access</message>
<message key="makepublic-stored-report">Publish</message>
<message key="makeprivate-stored-report">Hide</message>
<message key="stored-report-ownedby">(owner: {0})</message>
<message key="column.act.stop">--No more columns</message>
<message key="column.act.skip">--Skip this column</message>
If your skin provides an own styling for the savedreports.xsl then you'ld probably want to add these additional templates:
<xsl:template name="makepublic-button">
<!-- template that should introduce a html input element capable of submitting the surrounding form
i.e. either a type= submit or image -->
</xsl:template>
<xsl:template name="makeprivate-button">
<!-- template that should introduce a html input element capable of submitting the surrounding form
i.e. either a type= submit or image -->
</xsl:template>
From version 1.2 beta to 1.2
If you want to upgrade from 1.1 directly to 1.2, follow both the instructions for going from 1.1 to 1.2 beta and then the additional instructions here.
Not much structural changes in this release, except for one thing: the commons-httpclient has been upgraded. So before you redeploy to Cocoon, delete the existing version located at webapps/cocoon/WEB-INF/lib/common-httpclient.jar.
In the build.properties file in your configuration directory, you need to add the following property:
# if you want to keep your reports directory in a separate location from the
# rest of the configuration files, then you can change that by adjusting
# the following property:
reports.home=${conf.home}
From version 1.1 to 1.2 beta
Changes to assembly.xml, environment.xml and config.xml
Some changes need to be made to the assembly.xml, environment.xml and config.xml files as a consequence of the introduction of new components (AuthorisationManager, UserEntryStore and ReportStore).
For the assembly.xml and environment.xml, it is easiest to just copy the new versions over your own versions (since you probably didn't modify these anyway):
copy xreporter/src/conf/xr-assembly.xml to conf.home/sarconf/assembly.xml copy xreporter/src/conf/xr-environment.xml to conf.home/sarconf/environment.xml
For the config.xml, you can copy a new version of the config.xml over your version and edit it to suit your needs (as you did during the original xR eporter installation):
copy xreporter/src/conf/xr-config.xml to conf.home/sarconf/config.xml
Or you can also make the required changes immediately to your existing config.xml (but then you'll have to be more careful -- I really recommend following the first approach):
* the <database> element in the <reportmanager> element has been (re)moved
* the <authorisation-table> element in the <usermanager> element has been (re)moved
* the <authorisation-codes-file> element in the <datasource> element has been (re)moved
* The following configuration must be added for the authorisation manager
(containing the above moved configurations):
<authorisationmanager>
<database>
<connection-params>
<url>jdbc:mysql://localhost/xreporteradmin</url>
<user>xreporteradmin</user>
<password>xreporteradmin</password>
</connection-params>
<accesscontrol-table table-name="accesscontrol" report-id-column="report_id"
user-role-column="user_role"/>
<authorisation-table table-name="authcodes" user-column="username"
authcode-column="authcode"/>
</database>
<authorisation-codes-file>@conf.home@/conf/authorisationcodes.xml</authorisation-codes-file>
</authorisationmanager>
* The following configuration must be added for the user entry store (entirely new thing):
<userentrystore>
<database>
<connection-params>
<url>jdbc:mysql://localhost/xreporteradmin</url>
<user>xreporteradmin</user>
<password>xreporteradmin</password>
</connection-params>
<userentry-table table-name="userentrystore" user-column="username"
id-column="storage_id" function-column="function" sequence-column="sequence"
type-column="type" value-column="value"/>
</database>
</userentrystore>
* The following configuration must be added for the report store (also an entirely new thing):
<reportstore>
<database>
<connection-params>
<url>jdbc:mysql://localhost/xreporteradmin</url>
<user>xreporteradmin</user>
<password>xreporteradmin</password>
</connection-params>
<reportstore-table table-name="reportstore" id-column="id" user-column="username"
name-column="name" datasource-column="datasource_id"
report-definition-column="reportdef_id"/>
<reportstore-detail-table table-name="reportstore_detail" id-column="id"
function-column="function" name-column="name" value-column="value"/>
</database>
</reportstore>
New administrative database tables
xReporter has a new feature that allows to store parameter and condition values on a per-user basis. This feature requires a new database table to be present, which can be created using this statement:
create table userentrystore (
username varchar(50) not null,
storage_id varchar(50) not null,
function varchar(10) not null,
sequence numeric(5) not null,
type varchar(10) not null,
value varchar(255) not null,
primary key(username, storage_id, function, sequence)
);
Another new feature is that xReporter can now save report instances (i.e. all modifications a user made to a report such as completing the interaction steps, changing the column layout, ...). This requires the following tables:
create table reportstore (
id VARCHAR(50) not null,
username VARCHAR(50) not null,
name VARCHAR(255) not null,
datasource_id VARCHAR(255) not null,
reportdef_id VARCHAR(255) not null,
primary key (id),
unique (name, username)
);
create index rs_name_idx on reportstore (name);
create index rs_username_idx on reportstore (username);
create table reportstore_detail (
id VARCHAR(50) not null,
function VARCHAR(15) not null,
name VARCHAR(255) not null,
value VARCHAR(255) not null,
primary key(id, function, name)
);
Ideally, the above tables (userentrystore, reportstore and reportstore_detail) should be created on a database supporting transactions. For example, the reportstore and reportstore_detail tables are used for storing report instances. One report instance will require mulitple inserts on these tables, which should be considered as one atomic operation. It could also be that a report is being read (= multiple selects) while it is being removed by another request (since these reports are associated with one user, chances are pretty low, but still...).
Various
Previously you may have depended on xReporter to show reports alphabetically sorted based on their filename. This was in fact something that only worked on Windows systems. Since implementing the automatic detection of changes to report definition files, this no longer works. If you want your reports to be displayed in a particular order, use the <sortorder> element in the report definition instead (see also the example reports included in the testconf).
Changes to the presentation layer
What follows here is only relevant in case you created your own skin or made changes to the sitemap.xmap file.
There are two new pages in the xReporter front-end: one which shows the saved reports for a user, and one which allows to enter a name for a new saved report. This has resulted in the addition of two XSL's (savedreports.xsl and save_report.xsl). Additionally, the navigation should contain links to these new pages: on the output page there should be a link to "save", and in the general navigation their should be a link to "<context>/<lang>/savedreports ".
The sitemap has been extended with pipeline fragments embedded in matchers using the following patterns:
*/reports/*/save */savedreports */savedreports/*
There have been a few other changes to other stylesheets. The HTML output stylesheet will now show the a description of the QBE configuration (if any) and the values of parameters and conditions entered during the interaction steps. The Excel (Gnumeric) stylesheet also includes that info on an additional sheet.
Changes to the build system
We have again streamlined the build system some more. The previous method using the build.xml script in the conf.home directory, and the requirement to have a standalone Ant installed (while it is included within the xreporter and xreporter-cocoon directories) felt quite unnatural. All this script did was actually launch the build.sh or build.bat file in the xreporter or xreporter-cocoon directory, so it is more logical to directly execute those scripts. The only requirement for this was some modifications to these scripts so that they automatically derive their "conf.home" directory from the current directory. We also renamed the build scripts to xreporter(.bat) and xreporter-cocoon(.bat) respectively, and moved them into a bin subdirectory.
You can now either add these bin directories to your PATH environment variable or use absolute paths when executing the scripts.
The scripts are:
For Windows: xreporter\bin\xreporter.bat xreporter-cocoon\bin\xreporter-cocoon.bat For Unix: xreporter/bin/xreporter xreporter-cocoon/bin/xreporter-cocoon
It will probably be easiest to work when you add those bin directories to your PATH:
For Windows: set PATH=%PATH%;c:\...\xreporter\bin;c:\...\xreporter-cocoon\bin For Unix: export PATH=$PATH:/.../xreporter/bin:/.../xreporter-cocoon/bin
To deploy to xReporter, go to your xReporter configuration directory (aka conf.home) and execute:
xreporter deploy
To deploy to Cocoon, go to your xReporter configuration directory and execute:
xreporter-cocoon deploy
To make a new configuration, go to an empty directory and execute:
xreporter seed
This is the equivalent of the previous "newconf" target.
The build.properties file in the xReporter configuration directory is still used as before, but the following properties are not needed anymore: xreporter.home, xreporter-cocoon.home and script.style. To avoid confusion, it is best to remove it. The build.xml file in the configuration directory also isn't used anymore, so remove that one to. And finally, you don't need to have Ant installed anymore.
Another nice new feature is that you can now validate your reports against an XML Schema by entering the following command in your xReporter configuration directory:
xreporter validate
From version 1.0 to 1.1
New deployment mechanism
We have streamlined the deployment mechanism in this release. Now you can deploy to Phoenix and Cocoon from your configuration directory (the "conf.home" directory). This requires that you have Ant installed. Then you need to copy xreporter/src/conf/template/build.properties.sample to conf.home/build.properties and xreporter/src/conf/template/build.xml to conf.home/build.xml. Edit the build.properties file to match your installation. Then the deploy can be invoked by executing the following command from your conf.home directory:
ant deploy-phoenix or ant deploy-cocoon
The old way of deploying still works (in fact, it hasn't changed much except that you can now invoke the build from your conf.home directory and that the cocoon deploy now also needs to now the location of the conf.home).
More information on deployment (when and how do I need to redeploy, ...) can be found in the new deployment document.
If you were using the "test configuration"
The test configuration is now distributed in its own directory, it is no longer constructed by the build target "testconf". If you'd like to use the test configuration, it's easiest to just drop your old configuration directory and switch to the new one provided with xReporter. The only thing you need to do is adjust the database configuration parameters in the config.xml and datasources.xml.
If you were using your own configuration (created by build newconf)
The assembly.xml file was updated, therefore copy the file xreporter/src/conf/xr-assembly.xml to conf.home/sarconf/assembly.xml.
If you made any report parameterisation files, they will need to be moved. More specifically, files that were located in:
xreporter-cocoon/src/resources/custom/stylesheets/html/report
now need to be moved to
conf.home/reports/customlayout/html
The same is true for the PDF: ".../fo/report" files should be moved to " .../customlayout/fo". (but again, this only has to be done if you actually created parameterisation files, otherwise you can skip this).
The build script can now handle the deployment of the xreporter.sar file to Phoenix (and it's no longer needed to remove the xreporter subdirectory if you deploy that way). During this deployment, the build script will substitute any occurrence of @conf.home@ in the config.xml with the actual location of the conf.home directory. This makes it easy to move the conf.home directory to another location, without needing to adjust the config.xml. So you may want to replace any absolute path in the config.xml referring to the conf.home directory with @conf.home@. (this is optional, but highly recommended). In the case of our imaginary user 'jef', this can easily be done by replacing all occurrences of /home/jef/xreporterdata by @conf.home@.
All files that are created by the build script (such as xreporter.sar) are now put in the directory conf.home/build, instead of conf.home/lib. So you may want to remove all automatically generated files from the conf.home/lib directory (if you haven't put any files there yourself, that means you can remove all files in the conf.home/lib directory).
Check the conf.home/sarconf/config.xml for references to lib/sample-extensions.jar and change them to build/user-extensions.jar (notice that both the location and the name of that file changed!). Also in the config.xml, remove the following line:
<function name="IsOdd" class="sample.IsOddFunction"/>
Changes to make to Cocoon
Some changes have to be made to the Cocoon installation. First of all, since the directory structure of what we deploy has changed a bit, it is best to first remove it, so remove the following directory:
/home/jef/jakarta-tomcat/webapps/cocoon/mount/xreporter
For the new skinning system, the name of the skin needs to be configured by declaring an inputmodule. For this, edit the file cocoon.xconf and look for the <input-modules> element. Then add the following as a child of that element:
<component-instance name="xreporterdefaults"
class="org.apache.cocoon.components.modules.input.DefaultsMetaModule">
<values>
<skin>outerthought</skin>
</values>
</component-instance>
With this we specify that the skin named "outerthought" should be used. This is a new, prettier skin. To use the old skin, change this to "default".
The pipelines for the login pages in the root sitemap have changed to support the skinning, and new matchers for images and css files to be used on the login pages were added. Remove the old matchers completely. Then put the following map:pipeline element in there (as a child of the <map:pipelines> element):
<!-- xReporter login pipelines. These should be put outside the protected area, since the login
pages themselves obviously should not be protected. -->
<map:pipeline>
<map:match pattern="xreporter-login">
<map:read
src="mount/xreporter/resources/skins/{xreporterdefaults:skin}/html/login.html"
mime-type="text/html"/>
</map:match>
<map:match pattern="xreporter-loginfailed">
<map:read
src="mount/xreporter/resources/skins/{xreporterdefaults:skin}/html/loginfailed.html"
mime-type="text/html"/>
</map:match>
<!-- matcher to point to skin-specific images. Note that this circumvents the security,
but for skin files this normally doesn't matter -->
<map:match pattern="xreporter-login/images/*.gif">
<map:read
src="mount/xreporter/resources/skins/{xreporterdefaults:skin}/images/{1}.gif"
mime-type="image/gif"/>
</map:match>
<map:match pattern="xreporter-login/images/*.png">
<map:read
src="mount/xreporter/resources/skins/{xreporterdefaults:skin}/images/{1}.png"
mime-type="image/png"/>
</map:match>
<!-- matcher to point to skin-specific css files. Note that this circumvents the security,
but for skin files this normally doesn't matter -->
<map:match pattern="xreporter-login/css/*.css">
<map:read
src="mount/xreporter/resources/skins/{xreporterdefaults:skin}/css/{1}.css"
mime-type="text/css"/>
</map:match>
<!-- The logout matcher is also put outside the protected area, to prevent an
endless login loop: suppose the authentication-session has expired, and then
the user follows the logout link; this would then cause the login page to be
shown, and after login the user would be redirected to the logout page, which
would again cause the login page to be shown, etc -->
<map:match pattern="xreporter-logout">
<map:act type="session-invalidate"/>
<map:act type="request">
<map:parameter name="parameters" value="true"/>
<map:redirect-to uri="{goto}"/>
</map:act>
</map:match>
</map:pipeline>
We have updated the I18nTransformer to the latest Cocoon CVS version to take advantage of some new features. This requires to add the following to the cocoon.xconf file (as a child of the <cocoon> root element):
<component role="org.outerj.xreporter.cocoon.i18n.BundleFactory" class="org.outerj.xreporter.cocoon.i18n.XMLResourceBundleFactory" logger="sitemap"/>
If you changed the "custom stylesheets" ...
If you previously modified the stylesheets in the "custom" directory, then you have in fact already your own "skin". To make it usable by xReporter 1.1, do the following. First, create a directory where in which you'll put your skin, for example:
/home/jef/skins
Then, copy the custom directory to that directory, so you get:
/home/jef/skins/custom
You may now want to rename this directory to a more appropriate name, for example:
/home/jef/skins/myskin
Now edit all the XSL's below the myskin directory to change the xsl:import of the common stylesheets to use an additional "../" in the path (that is of course, if the stylesheet has such an xsl:import). For example, in the columns.xsl you'll find a statement like:
<xsl:import href="../../../common/stylesheets/html/columns.xsl"/>
which needs to become
<xsl:import href="../../../../common/stylesheets/html/columns.xsl"/>
The namespace to which the I18nTransformer reacts has changed, so the namespace declaration will need to be updated. In the default custom-directory from xReporter 1.1, the i18n namespace is only used in the layout.xsl stylesheet. So edit that file and change:
xmlns:i18n="http://apache.org/cocoon/i18n/2.0"
to
xmlns:i18n="http://apache.org/cocoon/i18n/2.1"
To actually use this skin, change the skin name in the cocoon.xconf:
<component-instance name="xreporterdefaults"
class="org.apache.cocoon.components.modules.input.DefaultsMetaModule">
<values>
<skin>myskin</skin>
</values>
</component-instance>
and when deploying, pass a property extra.skins.dir, so that your skin gets copied over to the Cocoon installation. When deploying with the "ant deploy-cocoon" command, add this property to the conf.home/build.properties file like this:
extra.skins.dir=/home/jef/skins
or when deploying in the classic way (with the build.sh/build.bat script), add this property as a command-line parameter: build.... -Dextra.skins.dir=/home/jef/skins.
Problems? Questions?
Let us know about them on the mailing list.
There are no comments.