Report structure

Reports access objects (records in the database) and attributes from those objects. If you look at an existing report, you’ll see references such as $F{contact}.firstName. This is a reference to the contact object which was passed to the report and will draw on the page the first name attribute of that contact.

You may also see joins between entities like this $F{application}.course.name. You can traverse across joins between entities in this way.

Reports are all able to take advantage of the entire Groovy language within all report fields. This can be extremely powerful since you can write any code you want to execute within the report engine. A simple example might be $F{enrolment}.courseClass.expectedHours ?: "not specified" which would print "not specified" if the class has no timetable. More sophisticated code can control the repeating sections on a page, sorting of data and much more.

Report properties

onCourse expects to see certain properties added to each report. The properties can be edited in JasperSoft Studio using by choosing from the menu Edit->Custom properties or by just editing the XML by hand. If you look at the example above, you’ll see all the common properties visible. At a minimum you need "keycode", "versionNumber" and "entity". Without these, your report will not be accepted by onCourse.

An example of the parameters found in a report files is:

XML

<property name="name" value="Certificate-Attendance"/>
<property name="entity" value="Enrolment"/>
<property name="isSubreport" value="false"/>
<property name="isVisible" value="true"/>
<property name="versionNumber" value="8"/>
<property name="keyCode" value="ish.oncourse.nonVetCertificate"/>
<property name="ish.oncourse.description" value="Report is generated at the conclusion of any non VET short courses to verify
            that the student attended all of the required number of classes.This report prints in
            Portrait format."/>

name
A name to display in the user interface to users wanting to print a report.

keyCode
Each report has to be identified in the system, therefore it is given an unique property called 'keyCode'. We strongly recommend that for any reports you customise, you use a different code. This will avoid an update of onCourse software overriding your report with new version from our developers. If you copy an onCourse report, you should definitely change this to your own code.

versionNumber
A whole number, has to be increased every time a report is changed otherwise your modifications may not be visible.

entity
Identifies which is the starting point for the report, ie. report with value 'Certificate' will be available in print menu for list of certificates.

isVisible
can only take value of 'true' or 'false', indicates whether the report is visible in the print dialog

isSubreport
some reports are just injected inside others, this allows to specify this fact and hide this report from the user choice

ish.oncourse.reports.following
Use this property if you need print many reports as one, just add to this property a report’s key (or keys). If you need put more then one key - separate keys with ";". Any reports in here will be automatically printed after the initial report. This is particularly useful for certificates.

ish.oncourse.reports.isObjectOnSeparatePage
If this property is set to true, then each record is printed on a separate page. This is useful for invoices (for example) which should start a new page after every invoice record.

ish.oncourse.reports.description
A description to show to users in the onCourse user interface. Put some text in here to describe what the report does.

Data fields

Attributes from any onCourse data object can be added as fields to your report. So if the report has an entity of "Room" then you can access its attributes directly like this $F{name}. You can find all the onCourse attributes in our https://www.ish.com.au/s/onCourse/doc/latest/api/[API
documentation].

You can also directly access relations in this way $F{site}.name and use the full power of the Groovy language in these expressions.
So for a report rooted in the Enrolment entity you might use ${courseClass}.course.modules?.nationalCode This expression will find the course linked to the current class, get a list of modules, take the first one (using a null safe operator so that nothing bad happens if there isn’t any modules liked at all), then display the national code.

Custom attributes can be accessed by passing the custom field name to the customField() method. For example, if a contact had a custom field called 'how did you hear', the data stored in this field could be referenced by: $F{contact}.customField("how did you hear").