Skip to main content

How the official payslip PDF is made

Every payslip can be produced as an official PDF. The server generates it with JasperReports from the stored payslip figures. This page covers how to open it and what it shows. The last part, Under the hood, follows one request from the click to the finished file for readers who want to know how it works.

Two payslip PDFs, and when to use which​

The application can produce a payslip PDF in two different ways. They look different and are controlled by different settings.

Payslip previewOfficial PDF
Opened fromRow menu View, or double-click the row. Also the run's Download All Payslips (ZIP)Row menu Official PDF
Made byYour browser (pdfme), from the payslip data plus the active templateThe server (JasperReports), from a fixed layout
DesignChangeable in Payroll Settings → Customize Payslip TemplateFixed. Changing it is a code change to payslip.jrxml
Payslip Display switchesRespectedIgnored: year-to-date and employer contributions are always printed
Run status notesNonePrints a DRAFT or VOID note when the run is not final
Company detailsCompany name and logoRegistered name, TIN, address and employer numbers from the Employer Profile

Use the preview when you want the employee-facing design. Use the official PDF when you need a record that shows the run status and the company's statutory identity, for example when answering an audit or a dispute.

Open the official PDF​

Requires payroll.manage, payroll.approve or payroll.payslip.view.

  1. Open Payroll Runs (/payroll-runs) and open the run.
  2. In the payslip register below the summary, find the employee. Filtering by name or payslip number is the quickest way.
  3. Open the row menu and choose Official PDF.

The PDF opens in a new browser tab. From there you can print it or save it. It is named payslip-{payslipNumber}.pdf, for example payslip-PS-42-10001.pdf.

If the tab opens and then closes again, a message at the corner of the screen explains why. The usual causes are a missing permission or a payslip that no longer exists.

DRAFT and VOID notes​

The notes line at the bottom of the PDF depends on the run's status:

Run statusNote printed
Approved, ProcessedNo warning. The payslip is final
PendingDRAFT: the figures may still change
Cancelled, RejectedVOID: the payslip was not paid, with the cancellation reason when one was recorded

If the run replaces an earlier, reversed run, the PDF also says which run it replaces.

What is on it, and where each part comes from​

The official PDF never recalculates pay. It prints what the payroll run stored when payslips were generated, and adds a year-to-date total.

Part of the PDFWhere it comes from
Company name and details lineThe Employer Profile: registered name, TIN and branch code, address, SSS, PhilHealth and Pag-IBIG employer numbers. See Government forms and statutory compliance
Employee, position, department, government IDsThe payslip row, as captured when it was generated
Pay period, pay date, run number and status, payment method and statusThe payslip row and its payroll run
EarningsThe payslip's stored figures. Basic pay and gross pay always show. Overtime, night differential, holiday pay, paid leave and allowances only show when they are not zero
DeductionsSSS, PhilHealth, Pag-IBIG and withholding tax always show. Other deductions are listed line by line from the payslip's deduction items
Net payThe payslip's stored net pay
Year to dateA database total of the employee's payslips for the same calendar year, up to this payslip's period, counting only Processed runs plus this payslip's own run
Employer contributionsThe employer's SSS (including EC), PhilHealth and Pag-IBIG shares. Shown for information only, not deducted
Attendance lineDays worked, leave days, absences and overtime hours from the payslip
NotesGeneration time, plus the DRAFT, VOID or replacement notes above

Under the hood​

This part is for developers and anyone curious about how a click becomes a PDF. Paths are relative to the repository root.

The request, step by step​

  1. The click. The run detail page (frontend/src/pages/payroll/PayrollRunDetail.tsx) renders RunPayslipsGrid (frontend/src/components/payroll/RunPayslipsGrid.tsx). Its official-pdf row action calls openOfficialPdf(row).
  2. Open the tab first. openReport() (frontend/src/components/reports/openReportFile.ts) calls window.open('', '_blank') before sending the request. Browsers only allow pop-ups that happen right after a click, so the tab is opened while the click still counts, and filled in later.
  3. Send the request. fetchPayslipPdf(id) (frontend/src/api/payrollReports.ts) calls GET /api/payroll-reports/payslip/{payslipId} through the shared axios client with responseType: 'blob'. The client's request interceptor (frontend/src/api/client.ts) adds the Authorization: Bearer header. If the access token has expired, the response interceptor refreshes it once and retries.
  4. Security filters. TenantContextFilter runs first and opens a global tenant scope. JwtAuthenticationFilter checks the token, reloads the user and their roles from the database, and narrows the scope to that user's tenant. Spring Security then checks two @PreAuthorize rules on PayrollReportController. The class-level rule admits any payroll or HR reporting role. The method-level rule on payslip() needs payroll.manage, payroll.approve or payroll.payslip.view. A failure returns 403.
  5. Controller to service. PayrollReportController.payslip() calls PayrollReportService.payslip(payslipId, username). The service runs in a read-only transaction.
  6. Load the payslip. PayslipRepository.findWithDetailsByPayslipId() loads the payslip with its employee, the employee's position and the payroll run in one query (@EntityGraph). No row means ResourceNotFoundException, which becomes 404. That includes payslips belonging to another tenant, because row-level security hides them.
  7. Gather the rest. PayslipReportRenderer.renderOne() collects everything else the page needs:
    • ReportContext.header() reads the Employer Profile (CompanyProfileRepository.findFirstByOrderByCompanyProfileIdAsc()).
    • PayslipDeductionItemRepository returns the itemized other deductions.
    • PayslipRepository.findYtdThroughPeriod() sums the year-to-date figures.
  8. Build one data row. row() turns all of that into one Map whose keys match the <field> names in payslip.jrxml. Earnings and deductions vary in length, so each list is joined into two newline-separated strings, one for labels and one for amounts. The template prints them in two stretching text boxes side by side.
  9. Fill the template. template() compiles backend/src/main/resources/reports/payslip.jrxml the first time it is needed and keeps the compiled report in memory after that. JasperFillManager.fillReport() combines that compiled report, the parameters (company name, company details, and the shared KitStyles style template) and a JRMapCollectionDataSource holding the row. The result is a JasperPrint, which holds the laid-out pages in memory.
  10. Export to PDF. JasperExporters.export(print, PDF) runs Jasper's JRPdfExporter, which writes the PDF bytes and sets the document title. The bytes come back wrapped in a RenderedReport (bytes, filename, format).
  11. Response. PayrollReportController.file() sends the bytes as application/pdf with Content-Disposition: inline (show in the tab rather than download) and Cache-Control: no-store.
  12. Show it. Back in the browser, openReport() turns the blob into an object URL, points the tab that was opened in step 2 at it, and releases the URL a minute later. On an error it closes the tab, and reportErrorMessage() reads the JSON error out of the blob for the message.

Every database connection this request uses goes through TenantAwareDataSource. On each checkout from the pool it runs set_config('app.tenant_id', …), and PostgreSQL's row-level security policies read that setting. So every query in steps 4 to 7 only ever sees the caller's own organisation's rows, even though none of the queries filter by tenant themselves.

Sequence diagrams​

The flow is split into two diagrams so each stays readable. The first covers the browser and the security checks. The second zooms into the reporting module, shown as the single report module participant in the first diagram.

1. From the click to the controller and back​

2. Inside the reporting module​

In both diagrams, every arrow into PostgreSQL goes through TenantAwareDataSource, so row-level security applies to every query.

Reporting module objects​

All backend classes below are in backend/src/main/java/com/motorph/payroll/.

ObjectJob in this flow
controller/PayrollReportControllerHTTP entry point for server-side reports. Holds the permission rules and turns a RenderedReport into the HTTP response (file())
report/PayrollReportServiceEntry point for every payroll report. Loads the payslip and hands it to the payslip renderer. Its myPayslip() sibling serves the employee self-service download, limited to the caller's own non-void payslips
report/PayslipReportRendererBuilds the data row, owns the cached compiled template, fills it, and exports. Also renders a whole run's payslips in one PDF (renderRun())
report/ReportContextShared helpers for every report: the company header, date and money formatting, name formatting
report/ReportHeaderCompany name and details line, the user who generated the report, and the time it was generated
report/kit/KitStyles and report/kit/ReportThemeThe named text styles (fonts, colours) that every report uses. ReportTheme holds the values. The payslip receives them as a JRTemplate parameter, so the .jrxml file contains no fonts or colours of its own
resources/reports/payslip.jrxmlThe payslip layout: one A4 page per data row. This is the only report kept as a hand-written template. All other reports are built in Java code
report/JasperExportersTurns a filled JasperPrint into PDF or XLSX bytes
report/RenderedReportThe finished file: bytes, filename and format

Changing the layout​

payslip.jrxml uses the JasperReports 7 file format. It opens in Jaspersoft Studio 7.x (Community Edition is fine). Studio 6.x cannot read it.

  • Styles arrive from KitStyles when the report is filled. Studio's preview does not have them, so the preview looks unstyled. Use the running application to see the real result.
  • Every $F{...} field in the template must match a key that PayslipReportRenderer.row() puts into the row map. A missing key fails when the report is filled, not when it is compiled, so open a real payslip after every change.
  • The compiled template is cached for the life of the backend process. Restart the backend (or rebuild its container) to pick up a changed .jrxml.

Reference​