How To Upgrade JRXML Liferay Commerce Order Templates

Issue

• Liferay Commerce upgraded its internal reporting engine to JasperReports 7, utilizing a new XML schema with a Jackson-based parser that renders older Jasper 6 JRXML files incompatible.

• How can I upgrade custom Commerce order templates to the JasperReports 7 standard to make my templates compatible, ensure long-term stability, and align with modern data protection standards?

Environment

• Liferay Commerce

Resolution

Follow these steps to prepare your environment, migrate your templates, and upload them to Liferay Commerce:

1. Prepare the Environment: Install and configure Jaspersoft Studio 7.x to use the correct compatibility version.

   1. Install Jaspersoft Studio 7.x.

   2. Navigate to:

      1. Windows/Linux: Window > Preferences; or

      2. macOS: Jaspersoft Studio > Settings.

   3. Navigate to Jaspersoft Studio > Compatibility.

   4. Set the Version field explicitly to 7.0.0 to prevent the editor from saving files in the incompatible, legacy v6 format.

2. Migrate Files from v6 to v7: Migrate the template files using the built-in utility, which handles schema conversions automatically.

   1. In the Project Explorer, right-click the folder or specific file you wish to update.

   2. Select JasperReports > Update JasperReports files.

   3. Verify the target version is 7.0.0 and click Finish.

Alternatively, open the older .jrxml file, make a minor edit, and click Save to rewrite the XML source automatically.

3. Verify Migration: Verify the migration successfully updated the XML namespace and elements.

   1. Open the .jrxml file in a text editor.

   2. Verify the legacy SourceForge URL (namespace header) is removed from the <jasperReport> tag (e.g., xmlns="http://jasperreports.sourceforge.net/jasperreports" should be removed).

   3. Verify the template uses unified <element> tags (e.g., <element kind="text"...> or <element kind="textField"...>) instead of specific tags like <staticText>.

4. Upload Files: Upload the updated template to Liferay Commerce.

   1. As an administrator, open the Global Menu and navigate to Commerce > Channels.

   2. Click the specific Channel you wish to update.

   3. On the General tab, scroll to the Orders section and locate the Print Order Template field.

   4. Click Select File and choose the updated .jrxml file.

   5. Click Save. The reporting engine automatically compiles and executes the updated source when an order report generates.

Additional Information

• This upgrade is required for any bundles leveraging a Liferay version that includes the fix for the private ticket LPD-82858, if a custom print order template is in use.
• If the default print order template is in use, the default template will automatically be updated when patching to the Liferay version containing the upgraded reporting engine.