Skip to main content

The concept of Report History Records

Every render request tells VeloxFactory what to produce. A ReportHistoryRecord remembers exactly what was asked for, what came back, and what the result looked like, permanently, until you decide otherwise. It is the foundation for traceability, debugging, and on-demand reprinting in VeloxFactory.

Screenshot placeholder: report-history-record.index.filtered.png
Report History Record overview with filters applied and status badges.

What Gets Stored

A ReportHistoryRecord is created at render time when createHistoryRecord: true is set in the request, or automatically when a print task is dispatched. It captures a complete snapshot of the rendering event:

Field Description
traceId Unique identifier shared across the render request, the history record, and any linked print task. Used to correlate events in logs and across systems.
reportConfig Reference to the ReportConfig that was rendered.
outputType The output type used: base64, url, or none.
apiPayload The complete render request body: parameters, data, flags, everything sent to the render endpoint. Stored as JSON.
apiResponse The complete API response returned by VeloxFactory, including any errors. Stored as JSON.
reportPdf The rendered PDF, Base64-encoded. Present on successful renders; null on failure.
reportPdfFileName The UUID-based filename assigned to the rendered PDF.
reportExcelFileName Filename of the xlsx export, present when a mailing asked for one. The file hangs on the record, is downloadable from it and is deleted with it.
reportThumbnail A thumbnail image of the first page of the rendered PDF. Generated asynchronously in the background after the record is created.
status Automatically calculated from the stored response. See below.
reportPrintTasks Every print job dispatched from this record, with printer, copies and status. A record can hold any number of them. reportMailTasks Every mail sent from this record, with recipients, subject, the rendered body and the attachment names. audit Who created the record and when, who last updated it, and which API token was used in either case. VeloxFactory derives creationMethod and updateMethod from it, Frontend or API, depending on whether a token was present on the request.

The audit block is what turns a history record into an answer to "who printed this". A render triggered by an integration carries the token it was made with, a render triggered in the browser carries the user.

How It Comes Back from the API

The record is stored in full, but a response only carries what you ask for. Four query parameters control this, and they matter, a history record with an embedded PDF is a large object:

Parameter Default Effect withApiPayloads true Includes apiPayloadBase64 and apiResponseBase64. Both are Base64-encoded, so the stored JSON survives transport unchanged. withMedia false Adds the media block with reportPdfBase64, reportPdfFileName and thumbnailBase64. withRelations false Adds the full reportConfig, plus reportPrintTasks and reportMailTasks. withAudit false Adds the audit block described above.

Without any of them a record comes back as a compact summary: ID, trace ID, output type, status and the payloads. That is the right shape for a list view, and it is what the frontend's history overview uses.

Status

The status of a ReportHistoryRecord is calculated automatically every time the record is saved, based on the content of the stored API response:

Status Meaning
Ok No errors in the response and a PDF was produced. The render completed successfully.
Error The response contains one or more errors. The render failed, the error messages are stored in the API response payload.
Render Fail No errors in the response, but no PDF was produced either. An edge case indicating something unexpected occurred during rendering.
Unknown Status could not be determined from the stored response.

History records are created for both successful and failed renders. A failed render still produces a complete record, including the error messages, which is often more useful than a successful one when something goes wrong.

The Thumbnail

When a history record is created, VeloxFactory dispatches a background job that converts the first page of the rendered PDF into a thumbnail image using pdftoppm (part of poppler-utils). The thumbnail is stored on the record and displayed in the history list and the report card grid, giving you an immediate visual of what was produced without opening the PDF.

ℹ️ Thumbnail generation runs asynchronously. The history record is available immediately after rendering; the thumbnail appears once the background job has completed. This requires the Laravel queue worker (Supervisor) to be running. If the queue is down, thumbnails will not be generated until it is back up.

Traceability and Debugging

The most valuable aspect of a history record is not the PDF, it is the payload. Every record stores the exact request that triggered the render and the exact response that came back. This means you can answer the following questions at any point in the future, without touching the calling application:

  • What parameters were passed to this render?
  • What data was submitted?
  • Was the render triggered via the frontend or the API?
  • What did VeloxFactory return, and did it succeed?
  • If it failed, what was the exact error message?

The traceId ties everything together. It is present on the history record, on any linked print task, and in the server logs. When something goes wrong in production and you have a traceId, you can pull the history record and reconstruct the entire event in seconds.

Screenshot placeholder: report-history-record.show.png
Report History Record detail page with status, payload, PDF preview and the actions.

Reprinting from a History Record

A successful history record holds the rendered PDF. That PDF can be dispatched to a printer at any time, without re-rendering the report, using the dedicated print endpoint:

POST /api/v1/report-history-record/{id}/print

{
  "printerName": "WarehousePrinter01",
  "numberOfCopies": 1
}

VeloxFactory creates a new ReportPrintTask from the stored PDF, assigns it a derived trace ID (the original trace ID with a short random suffix), and dispatches it to the print service. The original history record is linked to the new print task.

This is useful in several scenarios: a print job failed and needs to be retried, a physical document was lost and needs to be reprinted, or a record needs to be dispatched to a different printer than the one originally used.

ℹ️ Reprinting uses the stored PDF, it does not re-render the report. The document produced is identical to the original. If the report template or its data has changed since the original render, those changes are not reflected in the reprint.

This endpoint is also available directly from the frontend, the history record detail view has a Print button that opens a modal to enter the printer name and number of copies.

Screenshot placeholder: report-history-record.print.modal.png
Print dialog of a Report History Record with the printer picker and the copies field.

Mailing from a History Record

The same idea applies to mail. A stored rendering can be sent to anyone at any time, without re-rendering:

POST /api/v1/report-history-record/{id}/mail

{
  "mailer": "Office SMTP",
  "mailTemplate": "Report Delivery",
  "to": ["disposition@example.com"],
  "includePdf": true,
  "includeExcel": false,
  "sendAsync": false
}

VeloxFactory creates a new ReportMailTask from the stored PDF, gives it a derived trace ID, and sends the mail through the chosen mailer. Recipients, contact name and attachment names accept the same placeholders as a mailing in the render request, resolved against the parameters and rows stored on the record.

If includeExcel is set and the record does not have an xlsx yet, VeloxFactory builds one on the fly from the stored data and attaches it to the record. For a report fed by an SQL adapter whose rows were never part of the request, there is nothing to export, and the call answers with a clear error instead of an empty sheet.

In the frontend the detail view has a Mail button next to Print, opening a dialog with mailer, template, recipients, attachments and the background switch. Every mail sent from this record is listed on the record itself, and in the Mail Queue.

Screenshot placeholder: mailing.history-record-modal.png
Mail dialog of a Report History Record with mailer, template, recipients, attachments and the background switch.
ℹ️ Mailing uses the stored PDF too. The document that arrives is identical to the original rendering. The full reference is on Report Mailing.

Retention and Deletion

Automatic Purging

History records are automatically purged after a configurable number of days. The retention period is set via the PURGE_HISTORY_DAYS environment variable (default: 30 days). Purging runs as a scheduled background job, no manual intervention required.

Deletion Constraints

A ReportHistoryRecord cannot be deleted while any ReportPrintTask or ReportMailTask still references it. The linked tasks must be removed first. VeloxFactory provides a dedicated endpoint for the print tasks:

DELETE /api/v1/report-history-record/{id}/delete-all-report-print-tasks

This removes all print tasks associated with the record in one call. Mail tasks are purged on their own schedule, controlled by PURGE_MAILTASKS_DAYS, and can be deleted individually from the Mail Queue. Once no task references the record any more, the history record itself can be deleted, which also removes its PDF and its xlsx from disk.

Impact on ReportConfig Deletion

A ReportConfig cannot be deleted while any history records reference it. This is a deliberate constraint: the history exists as a permanent trace of what was rendered using that configuration. To remove a report configuration entirely, its history records and their linked print tasks must be cleared first, either manually or by waiting for the automatic purge to run.

Back to top