Skip to content

Using PDF Simulator to Test Reports

Jump to bottom
Jeremy edited this page Oct 17, 2019 · 1 revision

This page discusses how to use the PDF Simulator tool.

This can help break up the work required to update (or create) a report.

Introduction

Reports in Aspen can be broken down into two separate tasks:

  1. The java code. This is what queries the database for specific pieces of information. In most reports the data is stored in a ReportDataGrid.
  2. The JRXML code. This uses JasperReports to convert that data into PDFs.

Normally when you ask Follett to create a report: you expect them to do both of these tasks. But if you'd like to you can take charge of the PDF task yourself. (Or you can give that assignment to another contractor.) This may reduce the overall time it takes to develop (if you let two people work on the two tasks separately), and/or it may reduce costs if you can find someone to write the JRXML more cheaply.

(Also if you'd like to take charge of just the java task: feel free to reach out and I can show you how to easily convert a ReportDataGrid to a CSV or XLS file for you to test against!)

Also focusing on these tasks separately encourages you to look at edge cases (discussed more below), which may reduce maintenance over time.

Usage

The PdfSimulatorJavaSource includes lengthy notes on how to use it. I'll just sum them up here. The first time you run it:

  1. Open the tool
  2. Select an existing report
  3. You have to add a file to "import", so just add any JPG or PNG in this first run
  4. Click "Run". You'll get an error. That's OK.
  5. Open up the tool log and select the "RECOMMENDED COLUMNS" entry.
  6. Copy these column names
  7. Open a new spreadsheet
  8. Paste these column names
  9. Create several rows of mock data.

For example: I just ran this for a health report, and the columns included:

  1. Comment
  2. Date
  3. Status
  4. Name
  5. Status
  6. student.getGradeLevel()
  7. student.getHomeroom()
  8. student.getLocalId()

I can add rows that include mock data for all of these values.

When you've added a few rows: save your spreadsheet and run the import again. This time select your spreadsheet as the import file.

This time you'll see your PDF populate with the mock data you provided in your spreadsheet. (So now you're completely bypassing the java source code attached to that report. It can be buggy or empty and that won't affect your ability to test how the PDF looks.)

Testing Edge Cases

This approach can help you test edge cases. The most common edge cases are:

  1. Long fields. (See how the JRXML formatted if you have a really long name, for example.)
  2. Short fields. (Will the JRXML look bad if the homeroom is an empty string?)
  3. Null fields. (Type "null" in the spreadsheet cell to pass a literal null to the JRXML. Does anything break?)

Are there any other special fields on your report? For example: if there's a number test really high and really low values. (Or what about negative values? Or decimal values?)

In some cases you may want the report to throw an error for certain badly formatted/missing data. It's OK if that's the expected behavior, but this helps you more clearly test that condition.

Localizations / Translations

If you've translated your report into multiple languages: this tool produces a PDF in each supported translation.

Creating New Reports

All of the above assumed you were modifying an existing report. What if you want to create a new report from scratch?

You need to create a JRXML file. I maintain mine using a free "Jaspersoft Studio" plugin for Eclipse, but if you don't have Eclipse set up you can probably download and install Jaspersoft Studio directly.

You probably don't need to create a JRXML file completely from scratch. Grab an existing Aspen report and copy and paste the "format definition" XML into a new JRXML file to get started. When you're finished the final JRXML file may look nothing like the original, but this provides a nice starting point.

When you're ready to test your JRXML:

  1. Copy the raw XML (source).
  2. Create a new Aspen report and paste the JRXML into the "Format Definition" field. (Assign a name and ID to your report, too.)
  3. Set the "Report engine version" to the highest possible value.
  4. Under "Options" select "Compile Format".
  5. Click "Save".

Now -- even without any java source code -- the PDF Simulator tool can interface with this new report and generate PDFs for you.

I know I glossed over the "how to actually edit JRXML files" step, but that's because there are already rich/numerous tutorials online that discuss this in detail. If you have enough free time (ha!) you can probably expect to be able to make small changes to the JRXML yourself. Really becoming a nuanced JRXML master will take a lot of time/effort, though.

Clone this wiki locally