Upgrading from the Community Project

If you're running a Community Project (CP) instance of JasperReports Server and want to upgrade to a commercial version of JasperReports Server, follow the instructions in this chapter.

This upgrade process uses the JasperReports Server commercial WAR File Distribution release package and the included buildomatic scripts.

This CP to commercial upgrade procedure is valid only for upgrade within a major JasperReports Server release, for example 6.0 CP to 6.0 commercial.

This chapter contains the following sections:

General Procedure
Backing Up Your JasperReports Server CP Instance
Exporting Your CP Repository Data
Preparing the JasperReports Server 6.1 WAR File Distribution
Configuring Buildomatic for Your Database and Application Server
Upgrading to the Commercial Version of JasperReports Server 6.1
Starting and Logging into JasperReports Server 6.1
Re-Configuring XML/A Connections (Optional)

General Procedure

The upgrade procedure consists of the following main steps:

1. Back up your JasperReports Server CP instance.
2. Export your CP repository data.
3. Upgrade your instance to JasperReports Server Commercial.
4. Import your CP repository data.

If you customized or extended JasperReports Server CP, you need to keep track of these modifications and integrate them with your JasperReports Server commercial instance after completing the upgrade.

Backing Up Your JasperReports Server CP Instance

Backup the old JasperReports Server CP WAR file and jasperserver database in case a problem occurs with the upgrade. Perform these steps from the command line in a Windows or Linux shell.

These instructions assume you have Tomcat application server and the PostgreSQL or MySQL database. Other application servers require a similar procedure. If you have another database, consult your DB administration documentation for back up information.

Backing Up Your JasperReports Server CP WAR File

For example, for Apache Tomcat, back up the jasperserver directory from the <tomcat>/webapps folder:

1. Go to the <tomcat> directory.
2. Make a new directory named js-cp-war-backup.
3. Copy <tomcat>/webapps/ jasperserver to <tomcat>/js-cp-war-backup.
4. Delete the <tomcat>/webapps/jasperserver directory.

Backing Up Your JasperReports Server Database

Go to the location where you originally unpacked your CP WAR file distribution zip. (Or create a new local folder to hold your backup file.)

1. Go to the <js-install-cp> directory.
2. Run one of the following commands:
     For PostgreSQL on Windows or Linux:

cd <js-install-cp>

pg_dump --username=postgres  jasperserver  >  js-db-cp-dump.sql

     For MySQL on Windows:

mysqldump --user=root --password=<password> jasperserver > js-db-cp-dump.sql

For MySQL on Linux:

mysqldump --user=root --password=<password> --host=127.0.0.1 jasperserver >js-db-cp-dump.sql

For MySQL, if you receive an error about packet size, see the Troubleshooting appendix of the JasperReports Server Installation Guide.

Exporting Your CP Repository Data

Before exporting your CP repository data, check to see if you have the default_master.properties file in this directory.

<js-install-cp>/buildomatic/default_master.properties

This file holds settings specific to your JasperReports Server instance, such as your application server location and your database type and location. If you don't have this file, see Example Buildomatic Configuration .

To export your CP repository data:

1. Navigate to the buildomatic directory:

cd <js-install-cp>/buildomatic

2. Run buildomatic with the export target:

Windows:

js-ant.bat export-everything-ce -DexportFile=js-cp-export.zip

Linux:

./js-ant export-everything-ce -DexportFile=js-cp-export.zip

This operation uses the export option --everything, which collects all your repository data.

Remember the path to your exported file. You need to specify it when you import to your commercial JasperReports Server repository.

Preparing the JasperReports Server 6.1 WAR File Distribution

Use the buildomatic scripts included in the commercial 6.1 WAR file distribution release package for the upgrade. Follow these steps to obtain and unpack the commercial 6.1 WAR file distribution ZIP file:

1. The WAR file distribution comes in a compressed ZIP file named jasperreports-server-6.1-bin.zip. Download the WAR file distribution from Jaspersoft technical support or contact your sales representative.
2. Extract all files from jasperreports-server-6.1-bin.zip. Choose a destination, such as C:\Jaspersoft on Windows, /home/<user> on Linux, or /Applications on Mac OSX.

After you unpack the WAR File Distribution Zip, the resulting location is known as:

<js-install-pro>

Configuring Buildomatic for Your Database and Application Server

This upgrade procedure uses the buildomatic scripts included with the WAR File Distribution ZIP release package.

Example Buildomatic Configuration

The default_master.properties file handles the upgrade configuration. We provide a sample configuration file for each database. You must specify your database credentials and your application server location, and rename the file to default_master.properties.

PostgreSQL Example

This example uses PostgreSQL (the same general logic applies to other databases).

1. Copy postgresql_master.properties from:

<js-install-pro>/buildomatic/sample_conf

2. Paste the file to:

<js-install-pro>/buildomatic

3. Rename the file to: default_master.properties
4. Edit default_master.properties for your database and application server. Sample property values are:

appServerType=tomcat6 (or tomcat7, tomcat5, jboss, glassfish)

appServerDir=c:\\Apache Software Foundation\\tomcat-6.0.26 (for example)

dbUsername=postgres

dbPassword=postgres

dbHost=localhost

MySQL Example

This example uses MySQL (the same general logic applies to other databases).

1. Copy mysql_master.properties from:

<js-install-pro>/buildomatic/sample_conf

2. Paste the file to:

<js-install-pro>/buildomatic

3. Rename the file to: default_master.properties
4. Edit default_master.properties for your database and application server. Sample property values are:

appServerType=tomcat6 (or tomcat7, tomcat5, jboss, glassfish)

appServerDir=c:\\Apache Software Foundation\\tomcat-6.0.26 (for example)

dbUsername=root

dbPassword=password

dbHost=localhost

Upgrading to the Commercial Version of JasperReports Server 6.1

After configuring the default_master.properties file, you can complete the upgrade.

Make sure you've backed up your jasperserver database before proceeding.

Make sure you've backed up your old JasperReports Server WAR file before proceeding.

1. Stop your application server.
2. Start your database server.
3. Run the following commands:

Commands

Description

<span class="Code">cd <js-install-pro>/buildomatic</span>

<span class="Code">js-ant drop-js-db</span><span class="Code">js-ant create-js-db</span><span class="Code">js-ant init-js-db-pro</span>

The first command deletes your jasperserver db. Make sure it's backed up. The other commands recreate and initialize the database.

<span class="Code">js-ant import-minimal-pro</span>

Adds superuser, Themes, and default tenant structure.

js-ant import-upgrade -DimportFile=<path>/js-cp-export.zip -DimportArgs="--include-server-settings"

The -DimportFile argument should point to the
js-cp-export.zip file you created earlier.

On Windows, you must use double quotation marks (“) if your path or filename contains spaces. On Linux, you must use double quotation marks escaped with a backslash (\”) in this case.

<span class="Code">js-ant import-sample-data-upgrade-pro</span>

(Optional) Loads the 6.1 commercial sample data.

<span class="Code">js-ant deploy-webapp-cp-to-pro</span>

Delete the CP war file, and deploy the commercial (pro) war file.

On MySQL, if you receive an error about packet size, see the Troubleshooting appendix of the JasperReports Server Installation Guide..

Starting and Logging into JasperReports Server 6.1

Before starting the server:

1. Set up the JasperReports Server License.

Copy the <js-install-pro>/jasperserver.license file to the C:\Users\<user> directory (Windows 7 example)

For information about how to set up the license, see the JasperReports Server Installation Guide.

2. Delete any files in the <tomcat>\temp folder.
3. Delete any files, directories, or sub-directories in <tomcat>\work\Catalina\localhost.
4. Delete any jasperserver*.xml files that might exist in <tomcat>\conf\Catalina\localhost.
5. (Optional) Move any existing <tomcat-install>\logs files into a backup directory to clean up old CP log data.

For instructions on clearing directories, see Additional Tasks to Complete the Upgrade.

Now start your Tomcat, JBoss, or GlassFish application server. Your database should already be running.

Clearing Your Browser Cache

Before you log in, make sure you and your end-users clear the Browser cache. JavaScript files, which enable UI elements of JasperReports Server, are typically cached by the browser. Clear the cache to ensure that the newer files are used.

Logging into the Commercial Version of JasperReports Server 6.1

Log in using the following URL, user IDs, and passwords:

URL: http://localhost:8080/jasperserver-pro

User ID

Password

Description

superuser superuser

System-wide administrator

jasperadmin jasperadmin

Administrator for the default organization

Your jasperadmin password might be reset to the default setting by the upgrade operation. For example, the jasperadmin password might be reset to jasperadmin. For security reasons, you should change your jasperadmin and superuser passwords to non-default values.

Your JasperReports Server instance has now been upgraded from Community Project (CP) to commercial. If startup or login problems occur, refer to the Troubleshooting appendix of the JasperReports Server Installation Guide.

Re-Configuring XML/A Connections (Optional)

XML/A connection definitions contain a username and password for connecting the Web Services to the server. A commercial edition of JasperReports Server supports multi-tenancy, which allows multiple organizations on a single instance. The default organization is organization_1. Each user (except superuser) must belong to a specific organization. After upgrading to the commercial JasperReports Server, users belong to the default organization.

You need to update XML/A connection definitions to include the organization the user belongs to.

The XML/A connection also specifies an instance URI. You'll need to update this URI to the commercial instance. Edit your XML/A connections as shown in the following examples:

User IDs

Change “jasperadmin” to “jasperadmin|organization_1

Change “joeuser” to “joeuser|organization_1

URI values

Change:

http://localhost:8080/jasperserver/xmla

to

http://localhost:8080/jasperserver-pro/xmla

Additional Tasks to Complete the Upgrade

Perform these tasks with the application server shutdown.

Handling JasperReports Server Customizations

If you made modifications to the original JasperReports Server application, JasperReports Server 5.06.05.66.1 for example, these configurations are typically found in the WEB-INF/applicationContext-*.xml set of files.

You'll need to manually copy configuration changes, like client-specific security classes or LDAP server configurations, from your previous environment and integrate them with your upgraded environment.

Clearing the Application Server Work Folder

Application servers have work folders where JasperReports Server files are compiled and cached and other objects are stored. When you update the WAR file or license, the buildomatic deploy-webapp-pro target should automatically clear the application server’s work directory, but it’s a good practice to double-check. A permission problem, or some other problem, could prevent the clearing of the work folder.

To clear the work folder in Tomcat:

1. Change directory to <tomcat>/work.
2. Delete all the files and folders in this directory.

Clearing the Application Server Temp Folder

JasperReports Server uses caching to speed operations within the application. Caching files are created and stored in the application server, usually in a temp folder. Clear this temp folder to avoid any post-upgrade conflicts. Typically, the temp folder used by an application server corresponds to the path referenced by the java.io.tmpdir Java system property. For Apache Tomcat the temp folder is <tomcat>/temp.

To clear the temp folder in Apache Tomcat:

1. Change directory to <tomcat>/temp
2. Delete all the files and folders in this directory

Clearing the Repository Cache Database Table

In the jasperserver database, compiled JasperReports Library resources are cached in the JIRepositoryCache table for increased efficiency at runtime. Because the JasperReports Library JAR is typically updated with each new release, old cached items can get out of date and cause errors at runtime. If you encounter errors that mention a JasperReports Library “local class incompatible,” check your repository cache table. In summary, you can clear your jasperserver database cache table as part of this upgrade process whether or not there are errors.

To manually clear the repository cache database table, run a SQL command similar to one shown below:

update JIRepositoryCache set item_reference = null;

delete from JIRepositoryCache;

Version: 
Feedback
randomness