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 preview | Official PDF | |
|---|---|---|
| Opened from | Row menu View, or double-click the row. Also the run's Download All Payslips (ZIP) | Row menu Official PDF |
| Made by | Your browser (pdfme), from the payslip data plus the active template | The server (JasperReports), from a fixed layout |
| Design | Changeable in Payroll Settings → Customize Payslip Template | Fixed. Changing it is a code change to payslip.jrxml |
| Payslip Display switches | Respected | Ignored: year-to-date and employer contributions are always printed |
| Run status notes | None | Prints a DRAFT or VOID note when the run is not final |
| Company details | Company name and logo | Registered 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.
- Open Payroll Runs (
/payroll-runs) and open the run. - In the payslip register below the summary, find the employee. Filtering by name or payslip number is the quickest way.
- 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 status | Note printed |
|---|---|
Approved, Processed | No warning. The payslip is final |
Pending | DRAFT: the figures may still change |
Cancelled, Rejected | VOID: 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 PDF | Where it comes from |
|---|---|
| Company name and details line | The 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 IDs | The payslip row, as captured when it was generated |
| Pay period, pay date, run number and status, payment method and status | The payslip row and its payroll run |
| Earnings | The 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 |
| Deductions | SSS, PhilHealth, Pag-IBIG and withholding tax always show. Other deductions are listed line by line from the payslip's deduction items |
| Net pay | The payslip's stored net pay |
| Year to date | A 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 contributions | The employer's SSS (including EC), PhilHealth and Pag-IBIG shares. Shown for information only, not deducted |
| Attendance line | Days worked, leave days, absences and overtime hours from the payslip |
| Notes | Generation 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
- The click. The run detail page (
frontend/src/pages/payroll/PayrollRunDetail.tsx) rendersRunPayslipsGrid(frontend/src/components/payroll/RunPayslipsGrid.tsx). Itsofficial-pdfrow action callsopenOfficialPdf(row). - Open the tab first.
openReport()(frontend/src/components/reports/openReportFile.ts) callswindow.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. - Send the request.
fetchPayslipPdf(id)(frontend/src/api/payrollReports.ts) callsGET /api/payroll-reports/payslip/{payslipId}through the shared axios client withresponseType: 'blob'. The client's request interceptor (frontend/src/api/client.ts) adds theAuthorization: Bearerheader. If the access token has expired, the response interceptor refreshes it once and retries. - Security filters.
TenantContextFilterruns first and opens a global tenant scope.JwtAuthenticationFilterchecks 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@PreAuthorizerules onPayrollReportController. The class-level rule admits any payroll or HR reporting role. The method-level rule onpayslip()needspayroll.manage,payroll.approveorpayroll.payslip.view. A failure returns 403. - Controller to service.
PayrollReportController.payslip()callsPayrollReportService.payslip(payslipId, username). The service runs in a read-only transaction. - 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 meansResourceNotFoundException, which becomes 404. That includes payslips belonging to another tenant, because row-level security hides them. - Gather the rest.
PayslipReportRenderer.renderOne()collects everything else the page needs:ReportContext.header()reads the Employer Profile (CompanyProfileRepository.findFirstByOrderByCompanyProfileIdAsc()).PayslipDeductionItemRepositoryreturns the itemized other deductions.PayslipRepository.findYtdThroughPeriod()sums the year-to-date figures.
- Build one data row.
row()turns all of that into oneMapwhose keys match the<field>names inpayslip.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. - Fill the template.
template()compilesbackend/src/main/resources/reports/payslip.jrxmlthe 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 sharedKitStylesstyle template) and aJRMapCollectionDataSourceholding the row. The result is aJasperPrint, which holds the laid-out pages in memory. - Export to PDF.
JasperExporters.export(print, PDF)runs Jasper'sJRPdfExporter, which writes the PDF bytes and sets the document title. The bytes come back wrapped in aRenderedReport(bytes, filename, format). - Response.
PayrollReportController.file()sends the bytes asapplication/pdfwithContent-Disposition: inline(show in the tab rather than download) andCache-Control: no-store. - 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, andreportErrorMessage()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/.
| Object | Job in this flow |
|---|---|
controller/PayrollReportController | HTTP entry point for server-side reports. Holds the permission rules and turns a RenderedReport into the HTTP response (file()) |
report/PayrollReportService | Entry 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/PayslipReportRenderer | Builds the data row, owns the cached compiled template, fills it, and exports. Also renders a whole run's payslips in one PDF (renderRun()) |
report/ReportContext | Shared helpers for every report: the company header, date and money formatting, name formatting |
report/ReportHeader | Company name and details line, the user who generated the report, and the time it was generated |
report/kit/KitStyles and report/kit/ReportTheme | The 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.jrxml | The 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/JasperExporters | Turns a filled JasperPrint into PDF or XLSX bytes |
report/RenderedReport | The 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
KitStyleswhen 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 thatPayslipReportRenderer.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
- Payslips and payslip templates: the payslip register, the browser preview, bulk ZIP downloads and the template designer.
- Run a payroll: the run statuses that decide the DRAFT and VOID notes.
- How each figure on the payslip is computed: Business Rules.