Article verified for Release 15.1 on September 1, 2025.

This article explains the procedure for creating custom certificate templates. A certificate template is a .jasper file (Jasper report) produced by compiling a .jrxml file. Creation and compilation of .jrxml files are performed using Jasper reports software. We will refer to both .jrxml and .jasper documents as templates.

Software installation

We will use Jaspersoft Studio to create .jasper files. It is a standalone software that offers the same environment as the Eclipse plugin, Jaspersoft Studio. For compatibility, please ensure you are using at least Jaspersoft Studio version 6.21.3. It can be downloaded using the following link, as shown in the figure below. Choose the version for your operating system (Windows, Linux, or macOS).

Installation / Extraction

Depending on the package you download:

• Installer (.exe / .dmg)
  Run the installer and follow the setup wizard.
• Archive (.zip)
  Extract the contents to any preferred location. No installation is required.

3. Launch

Open the application by running:

• Jaspersoft Studio.exe on Windows
• The Jaspersoft Studio application file on macOS or Linux

Default templates

When creating a desired template, you can start from a completely new Jasper report by selecting File > New > Jasper report. However, YouTestMe provides four default templates that you can import and edit. These templates offer a flexible starting point, allowing you to modify and customize your certificates.

The included templates are:

• Portrait Orientation
• Landscape Orientation
• Rounded Header
• Golden Header Line

Select the template you want to use to streamline the certificate creation process, designing certificates that fit your requirements.

Here, we will assume that you have chosen the second option (Landscape Orientation).

Importing templates

Start by importing the default templates into your project in JasperSoft Studio. The steps are shown in the figures below:

1. Click File in the top menu to access the main application options.
2. Select Import to open the file import wizard.
3. When the import window appears, expand the General folder to view available sources.
4. Choose File System as the import type for files from your local computer.
5. Click the Next button to proceed to file and destination selection.

After that:

1. Click on the Browse button.
2. Select the folder where you store the default templates.
3. Confirm the selected folder.

Now, you can:

1. Select the template you want to use.
2. Choose MyReports as the destination folder.
3. Click the Finish button to complete and save the import.

Double-click the desired template in the left menu. You can now modify the properties of existing elements (images, text fields), remove them, or add new elements. Additionally, you can adjust properties for the entire report, such as page size, orientation, margins, and more.

Default templates analysis

Here we will explain in more detail one of the default templates, and then we will walk through creating a custom template.

The figure below shows that the template elements are placed in a Detail band, and when exportCertificate on the top of the Outline window is clicked, we can see the properties of the entire report on the right. By clicking the Edit Page Format button, a dialog appears where you can modify page size, orientation, margins, etc. After this operation, make sure the Language property is set to “Java” (sometimes it changes by itself after changing the page size).

Now, we will look more closely at the image used as the template background. The analysis can be applied to other images as well. The background image should equal the page size, i.e., it occupies the whole Detail band.

Click the corresponding image element in the Detail band, and you will see the physical properties of the element, as shown below:

Under the Image tab, there are two very important properties. The first one is Expression, where you can choose whether to import the image for this image element from the file system or to enable importing it in the application. This will be explained later with an example. The second property is Scale Image, which specifies how the imported image will be scaled in the template. The three most important options are “Fill Frame”, where the image will occupy the whole image element size regardless of its aspect ratio (relation between image’s width and height), Retain shape, where the picture will stretch to fit one dimension and leave blank space in another dimension if its aspect ratio does not match the aspect ratio of the image element, and Real size, where the image retains its real size in pixels.

Supported Variables for Custom Certificates

When designing or modifying a template, you can insert variables that will be automatically replaced with user, test, and certificate information at runtime. These variables can be inserted as text fields within the template, allowing you to generate personalized certificates dynamically.

The following variables are currently supported:

• User Information
  userId, userFirstName, userLastName, userFullName, userUsername, dateOfBirth, country, userGroupName (name of a user group assigned to a session)
• Certificate Information
  certificateId, certificateName, certificateDescription, certificateCompany, expiryDate (certificate expiration), certifyDate (certificate creation date)
• Logos and Design
  certificateLogo, companyLogo, backgroundTheme, defaultLogo, defaultCompanyLogo, defaultBackground
• Test Information
  quizDefinitionId (test ID), quizName, quizDescription, testLabel, percentScored, uniqueQuizId (test version ID), uniqueQuizName (test version name), quizFinishDate (when the test was finished), quizInstanceId, displayTestName, displayTitle, displayScore, displayDateOfIssue, displayExpiryDate, displayUniqueId, testExternalId, gradingSystemId, grade
• Session Information
  testingSessionId, testingSessionName, testingLocationName, sessionAvailableFromDate, userGroupName

These variables can be combined with static elements (such as background images or fixed text) to produce fully customized and dynamic certificates.

In addition to simple variables and fields, certificates can include more complex data such as test categories.

Print test categories

• Field name: testCategories
• Class: java.util.List
• Data source expression: 
  new net.sf.jasperreports.engine.data.JRBeanCollectionDataSource($F{testCategories})

• Fields in a record:

  • key – String

  • value – String

To display categories in a Key: Value format: $F{key} + ": " + $F{value}

How to Save a Created Certificate Template

1. Open Project Explorer.
2. Navigate to My Reports.
3. Select the .jrxml template you have been editing and press Ctrl + S to save your changes.
4. Click the Compile Report button to generate the compiled template.

Example – Modifying a default template

Now, we will go through an example. Let’s imagine we want the image below to be the background image in default_template_landscape.jrxml. The file name is OriginalBackgroundImage.png.

First, we import the image from the file system into the template to place other elements in the desired positions concerning the background. The steps are shown in the figure below. We are changing the properties of the image element representing the background image in the template.

Since the Scale Image property is set to Fill Frame, the imported image will scale to fit the image element size.  If it is not essential for you to preserve the image aspect ratio, importing the background image is finished here. The next step is to place other elements at appropriate positions, change their properties, remove some elements, add new elements, etc.

However, if preserving the imported image aspect ratio is required, we change the Scale image property to Retain shape.  Since the imported image has a lower aspect ratio (width/height = 1.29) than the default template page size (A4 format, width/height = 1.41), we see the blank space on the right in the figure below. The goal is to remove this blank space, i.e., to adjust the image element size to the imported image.

Note that only the aspect ratio of the imported image is preserved (Retain shape), not the original size.

If the original size is to be preserved, then the Real size option should be chosen. This option should be used when it is very important to preserve the quality of the image.

We adjust the corresponding image element size (842 x 595) to the imported image size (770 x 595), as shown below:

Now we reset the Expression of the image background element, making use of the corresponding field (backgroundTheme in this case), so it can be imported into the template at the time of creating a certificate in the application.

After saving and compiling the default_template_landscape.jrxml, you get the default_template_landscape.jasper file, which you can use when creating a new certificate, as shown below:

After compiling the .jasper file, to add the template to the GetCertified, do the following:

1. Select the System > System and customization tab.
2. Select the Templates tab.
3. Click on the Create new button.
4. Enter the name of the certificate.
5. Optionally add a description.
6. From the drop-down list, choose a template type.
7. Upload the previously created .jasper file.
8. Click on the Save button to add the template to the system.

After adding the template, create a certificate from the Tests/Manage certificates tab:

1. Select the Add new template button to apply the template to the certificate.
2. Select the background image.
3. Click the Preview button to see how the template is applied to the background image.
4. Click on Save to save the certificate.

In step 1, you upload the default_template_landscape.jasper file to be used as the template for the certificate is created. In step 2, you upload the image you want to use as a background, in this case, OriginalBackgroundImage.png.

What if you want to create a certificate that has 2 pages? It is very simple. You only need to add a new Detail band to default_template_landscape.jrxml and set its elements and properties similar to the existing Detail band.

Custom certificate templates can also be added to the user’s achieved Certificates list on the user’s profile. To do this, select the assigned certificate. You can:

1. Choose the previously created custom certificate from the drop-down list using a template.
2. Select the validity period for the certificate.
3. Save the changes.

For more information, please watch this video: