Jump to content
Changes to the Jaspersoft community edition download ×
  • This documentation is an older version of JasperReports Server Upgrade Guide. View the latest documentation.

    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.

    warning-icon-ns_28x28.png.535629b01a1449b148d9dfd72d871a26.png

    This CP to commercial upgrade procedure is valid only for upgrade within a major JasperReports Server release, for example 7.9 CP to 7.9 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 7.9 WAR File Distribution
    Configuring Buildomatic for Your Database and Application Server
    Upgrading to the Commercial Version of JasperReports Server 7.9
    Starting and Logging into JasperReports Server 7.9
    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

    Back up 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

    note-icon-ns_28x28.png.17d67dcb9045fe12706e21d78e7ac017.png

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

    Backing Up Your Keystore

    Back up your JasperReports Server Keystore:

    1. Create a folder (if you did not do so already) where you can save your server's keystore, for example C:JS_BACKUP or /opt/JS_BACKUP.
    2. As the user who originally installed the server, copy $HOME/.jrsks and $HOME/.jrsksp  to  <path>/JS_BACKUP. Remember that these files contain sensitive keys for your data, so they must always be transmitted and stored securely.

    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:

    Linux:

    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 7.9 WAR File Distribution

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

    1. The WAR file distribution comes in a compressed ZIP file named TIB_js-jrs_7.9.0_bin.zip. Download the WAR file distribution from TIBCO Jaspersoft Technical Support (http://support.tibco.com) or contact your sales representative.
    2. Extract all files from TIB_js-jrs_7.9.0_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=tomcat (or wildfly, etc.)

    appServerDir=c:Apache Software FoundationTomcat 9.0 (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=tomcat (or wildfly, etc.)

    appServerDir=c:Apache Software FoundationTomcat 9.0 (for example)

    dbUsername=root

    dbPassword=password

    dbHost=localhost

    Upgrading to the Commercial Version of JasperReports Server 7.9

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

    warning-icon-ns_28x28.png.a4b854faf3abf7c380f1fa91498c62e6.png

    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. Make sure that the user running the upgrade commands is the same user that installed the server.
    4. Run the following commands:

    Commands

    Description

     

    js-ant drop-js-db[/code]
    js-ant create-js-db[/code]
    js-ant init-js-db-pro[/code]                    

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

    Adds superuser, Themes, and default tenant structure.

    Windows:

    js-ant import-upgrade
    -DimportFile="<path>/js-cp-export.zip"
    -DimportArgs="--include-server-settings
    --secret-key='0x1b 0xd4 0xa6 ...'"

    Linux:

    js-ant import-upgrade
    -DimportFile="<path>/js-cp-export.zip"
    -DimportArgs="--include-server-settings
    --secret-key='0x1b 0xd4 0xa6 ...'"

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

    --include-server-settings --secret-key specifies the key to use for the import. Use the same key you imported into the keystore.

    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.

    (Optional) Loads the 7.9 commercial sample data.

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

    note-icon-ns_28x28.png.dc0a0539154d574e9f38bcacb139eb2c.png

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

    If you are prompted to create a new keystore, this means that the server's original keystore was not found in the user's home directory. Proceed with caution:

    In general, it is recommended to exit the upgrade procedure and make sure the keystore is in the proper location, then rerun the upgrade.
    If you continue and create a new keystore, then the upgrade will proceed but your repository will be corrupted and users unable to login. In this case, you will need to export the server's repository with a custom key as described in Encryption Keys. Then replace the import-upgrade commands in the table above with the following ones that specify the secret-key value from the export:

    Windows

    Linux

    Starting and Logging into JasperReports Server 7.9

    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>workCatalinalocalhost.
    4. Delete any jasperserver*.xml files that might exist in <tomcat>confCatalinalocalhost.
    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 or JBoss 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 7.9

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

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

    User ID

    Password

    Description

    System-wide administrator

    Administrator for the default organization

    warning-icon-ns_28x28.png.f328de1f873f03a4072699d72546e402.png

    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 TIBCO 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 shut down.

    Handling JasperReports Server Customizations

    If you made modifications to the original JasperReports Server application, 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;


    User Feedback

    Recommended Comments

    There are no comments to display.



    Guest
    This is now closed for further comments

×
×
  • Create New...