Configuring excerpt templates in PDF, DOCX, CSV formats

On this page:

1. Overview
2. Configuring excerpt templates
3. Common errors and troubleshooting
- 3.1. Incorrect template format
- 3.2. Font conflict
4. Data history excerpt
5. Related pages

🌐 This document is available in both English and Ukrainian. Use the language toggle in the top right corner to switch between versions.

1. Overview

To generate and download excerpts in .pdf, .docx, or .csv formats, you must configure the appropriate templates in the registry’s regulation settings in advance.

The administrator must add an excerpt template and its attributes to the regulation directory, specifically:

for .pdf — excerpts/excerpt-name-pdf/index.html.ftl;
for .docx — excerpts-docx/excerpt.docx;
for .csv — excerpts-csv/excerpt-csv.json.

The Platform uses Apache FreeMarker in extract templates, but with an alternative tag syntax. This differs from the standard syntax described in the official FreeMarker documentation. See more about using this alternative syntax at link.

Keep this in mind when setting up templates to avoid errors in processing and display.

Figure 1. Structure of regulation for generating excerpts in PDF, DOCX, and CSV formats

excerpts, excerpts-docx, excerpts-csv — mandatory directory names for excerpts in the respective format.
index.html.ftl, excerpt.docx, excerpt-csv.json — examples of excerpt file names.

The names of each directory and file must be unique, even across different formats. The system uses these templates to create excerpts in the registry’s user interface.

For setting up localized excerpts in the required language, refer to the page registry-admin/excerpts/localized-excerpts.adoc.

2. Configuring excerpt templates

2.1. Configuring templates for PDF excerpts

To configure a PDF excerpt template:

Access the local Gerrit repository in your registry.

Add the index.html.ftl template file to a directory with a unique name, for example, excerpts/excerpt-pdf-1.

The PDF extract template must be created in .html.ftl format using Apache FreeMarker with alternative tag syntax. This templating tool allows variables to be inserted in PDF (.html.ftl) or .docx templates. Use FreeMarker expressions to insert variables:

<html>
   <body>
      <h1>Extract for [=userName]</h1>
      <p>Date: [=currentDate]</p>
   </body>
</html>

Here, [=userName] and [=currentDate] are variables whose values will be populated during document generation. Be sure to use FreeMarker’s alternative tag syntax to avoid errors in processing.

Create and save the style file style.css in the directory excerpts/excerpt-pdf-1/css.

You can use multiple style files. To do this, link each file in the template:

<html>
   <head>
      <meta charset="UTF-8">
      <link rel="stylesheet" href="style-1.css">
      <link rel="stylesheet" href="style-2.css">
      <style>
         * { font-family: Roboto; }
      </style>
   </head>
   <body>
      <h1>Excerpt Title</h1>
      <p>This is an example of PDF document content.</p>
   </body>
</html>

Use UTF-8 encoding. The default font should be Roboto. Using other fonts may cause errors.

To specify landscape orientation, adjust style.css:

@page {
    size: 15in 8.5in;
    margin: 0.75in 0.9in;
}

Set the size parameter to the width and height of the file in inches.

Add an image in .png format to the excerpts/excerpt-pdf-1/images directory. Use the image reference in the template:

<img src="images/image.png" alt="Image description" width="300">

In this example, an image from the images folder, located in the template directory, is used. The alt attribute provides alternative text if the image does not display, and the width attribute sets the image width in pixels.

The final template version with an added image may look like this:

<html>
   <head>
      <meta charset="UTF-8">
      <link rel="stylesheet" href="style-1.css">
      <link rel="stylesheet" href="style-2.css">
      <style>
         * { font-family: Roboto; }
      </style>
   </head>
   <body>
      <h1>Extract Title for [=userName]</h1>
      <p>Date created: [=currentDate]</p>
      <p>The image used in this extract is shown below:</p>
      <img src="images/image.png" alt="Image description" width="300">
      <p>Additional information about the extract can be added here.</p>
   </body>
</html>

Save changes to the remote Gerrit repository (for more details, see Deploying registry regulations in Gerrit).
After updating the regulation, PDF excerpts can be generated in the Citizen Portal (see details at Generating excerpts in PDF format).

2.2. Configuring templates for DOCX excerpts

To configure a DOCX excerpt template:

Access the local Gerrit repository.
Add the excerpt.docx file to the excerpts-docx directory.
Save changes to the remote Gerrit repository (for more details, see Deploying registry regulations in Gerrit).
After updating the regulation, DOCX excerpts can be generated in the User Portal (see details at Generating excerpts in DOCX format).

Download a sample excerpt in .docx format: Sample DOCX template.

An example of business process modeling for generating CSV and DOCX excerpts is available at: Modeling business processes for generating excerpts in csv and docx format.

2.3. Configuring templates for CSV excerpts

To configure a CSV excerpt template:

Access the local Gerrit repository.

Add the excerpt.json file to the excerpts-csv directory.

To configure column headers, create a .json file with header mappings:

{
"lastName": "Last Name",
"firstName": "First Name",
"secondName": "Middle Name",
"birthday": "Date of Birth",
"residenceAddress": "Address",
"phoneNumber": "Phone",
"gender": "Gender"
}

The keys in the left column correspond to the parameter names in the system, and the values in the right column are the new names displayed in the excerpt.

Save changes to the remote Gerrit repository (for more details, see Deploying registry regulations in Gerrit).
After updating the regulation, CSV excerpts can be generated in the User Portal (see details at Generating excerpts in CSV format).

An example of business process modeling for generating CSV and DOCX excerpts is available at: Modeling business processes for generating excerpts in csv and docx format.