# Meet the frontend

<div style="text-align: justify;">

VeloxFactory comes with a built-in web frontend that gives you full access to every feature without writing a single line of code. It is built with Laravel Livewire, a reactive framework that delivers a dynamic, app-like feel while keeping everything server-rendered. No separate JavaScript build, no SPA complexity.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>report-config.index.png</code><br>Report Config overview, the landing page after login, with context badges and thumbnails.
</div>

---

<h3 style="color: #203671; margin-top: 2.2em;">Navigation</h3>

After logging in you land directly on the **Report Configs** overview, the central workspace. Dedicated scan users without edit rights for report configurations land on **Scan2Print** instead. All other sections are reachable from the main navigation.

| Section | What you manage here |
|---|---|
| **Report Configs** | Your report templates, the heart of VeloxFactory |
| **Report History Records** | Every past rendering with status, payload, and PDF |
| **Report Print Tasks** | Print jobs dispatched to the print service |
| **Mail Queue** | Every mail that was sent or is waiting to go out, see [Report Mailing](/books/veloxfactory/page/report-mailing-sending-renderings-by-mail) |
| **Job Scheduler** | Recurring renders and the cleanup run, plus the log of every run, see [The Job Scheduler](/books/veloxfactory/page/the-job-scheduler-work-that-happens-without-you) |
| **Scan2Print** | Mobile scan station that turns every barcode scan into a print job, see [Scan2Print: Printing labels by scanning](/books/veloxfactory/page/scan2print-printing-labels-by-scanning) |
| **Report Contexts** | Organisational labels and visual tags for reports |
| **Report Connection Configs** | Live database connections for SQL-driven reports |
| **Common Report Resources** | Shared graphic assets, used by reports and as inline graphics in mails |
| **Printers** | Master data for your physical printers, see [Printers](/books/veloxfactory/page/printers-master-data-for-your-print-targets) |
| **Mailers** | Master data for your SMTP accounts, see [Mailers](/books/veloxfactory/page/mailers-master-data-for-your-smtp-accounts) |
| **Mail Templates** | Subject, body and whitelabeling of your mails, see [Mail Templates](/books/veloxfactory/page/mail-templates-subject-body-and-whitelabeling) |
| **Users** | User accounts and API token management |

The last seven entries are grouped under **Configuration** in the main navigation. They are master data you set up once and then pick by name everywhere else.

---

<h3 style="color: #203671; margin-top: 2.2em;">The Lookup Pattern</h3>

Every section opens with a **list view**, powered by a Livewire Lookup component. These views work the same way across all sections, so once you know one, you know them all.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>report-config.index.filtered.png</code><br>Report Config overview with the filter bar open and active filter badges.
</div>

<h4 style="color: #203671; margin-top: 1.4em;">Full-Text Search</h4>

A search bar at the top filters records instantly as you type, no page reload, no submit button. Depending on the section, the search covers names, descriptions, file names, and query text.

<h4 style="color: #203671; margin-top: 1.4em;">Column Filters</h4>

Each list view offers contextual filter dropdowns tailored to the entity. For Report Configs, for example, you can filter by Context, Data Adapter, Creator, or date ranges for creation and last update. Active filters are indicated by a badge count on the respective dropdown so you always see at a glance which filters are in play.

<h4 style="color: #203671; margin-top: 1.4em;">Pagination</h4>

Results are paginated. The default page size is controlled by the `PAGINATION_DEFAULT_COUNT` environment variable (default: 25). See [Configuration and Data Models](/books/veloxfactory/page/configuration-and-data-models) for all available environment settings.

<h4 style="color: #203671; margin-top: 1.4em;">Persistent Filters and Paging</h4>

Every list view remembers its state. The search term, all column filters (checkboxes, dropdown selections, date ranges) and the current page are stored in your session as soon as you change them. You can open a record, switch to another section and come back later, the list shows exactly the same filters and the same page as before.

The state is kept separately for each list view. Filters set on History Records do not affect Report Configs or any other section.

To start over, click the **reset button** of the respective list view, the dark button with the curved arrow icon between the search bar and the green **Filter** button. It clears the search term and all filters of this view and returns to the first page. All other views keep their filters.

<div style="border-left: 4px solid #5fc75d; background: #f6fdf6; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
ℹ️ <strong>Filters are stored per user session.</strong> They survive page reloads and navigation, but are cleared on logout or when the session expires. Filters are never shared with other users or other browser sessions.
</div>

---

<h3 style="color: #203671; margin-top: 2.2em;">Working with Report Configs</h3>

The Report Config section has the richest set of actions and is where most of your day-to-day work happens.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>report-config.edit.png</code><br>Report Config edit view with parameters, fields and resources.
</div>

<h4 style="color: #203671; margin-top: 1.4em;">Uploading a Template</h4>

Report templates are designed in **Jaspersoft Studio** (compatible version: **6.21.5**) and exported as `.jrxml` files. Once you have a `.jrxml` ready, you upload it to VeloxFactory to create a new Report Config. VeloxFactory immediately analyses the file and automatically creates all associated Parameters, Fields, and Resources, based on what is defined in the template. You do not need to add these manually.

After upload you review the auto-generated records: set example values where missing, assign a Data Adapter if the report uses SQL, and upload any resource files that were detected.

<h4 style="color: #203671; margin-top: 1.4em;">Managing Parameters, Fields, and Resources</h4>

Parameters, Fields, and Resources each have their own section within the Report Config edit view. You can edit example values, mark parameters as required, upload resource files, or link a resource to a Common Report Resource, all from the same screen.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>report-resource.edit.png</code><br>Report Resource edit view with the file upload and the link to a Common Report Resource.
</div>

<h4 style="color: #203671; margin-top: 1.4em;">Generating Previews</h4>

Once all example values are set and all resource files are uploaded, you can generate a preview rendering directly from the edit view. VeloxFactory renders the report using the stored example values and stores the result as a preview image and thumbnail on the Report Config.

<h4 style="color: #203671; margin-top: 1.4em;">Rendering from the Frontend</h4>

You can trigger a full render directly from the frontend, without touching the API. A render dialog lets you fill in parameter values, choose an output type, and optionally dispatch a print job or a mail in the same step. The result is shown inline and logged as a History Record if desired.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>generate-pdf.create.png</code><br>Generate PDF page with the parameter inputs and the output settings.
</div>

---

<h3 style="color: #203671; margin-top: 2.2em;">Report Connection Configs</h3>

When creating or editing a Connection Config, the form includes a **Test Connection** button. Use it before saving, a connection must be in status <span style="color: #349b31; font-weight: 600;">approved</span> before VeloxFactory will use it for rendering. An untested or failed connection will cause render requests to be rejected.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>report-connection-config.edit.png</code><br>Report Connection Config edit form with the Test Connection button.
</div>

---

<h3 style="color: #203671; margin-top: 2.2em;">Report History Records</h3>

The History Records section gives you a full log of every rendering that was saved. For each record you can see the status, the exact parameters and data that were submitted, the raw JasperReports response, and, if the rendering succeeded, the resulting PDF.

From a History Record you can:

- **Download** the PDF directly to your browser, and the xlsx export if the record has one
- **Trigger a print job**, creates a new Print Task for this specific rendering and dispatches it to the print service
- **Send it by mail**, opens a dialog for mailer, template, recipients and attachments and creates a new Mail Task

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>report-history-record.show.png</code><br>Report History Record detail page with status, payload, PDF preview and the actions.
</div>

---

<h3 style="color: #203671; margin-top: 2.2em;">Report Print Tasks</h3>

The Print Tasks section shows all dispatched print jobs and their current status. For each task you can inspect the target printer, number of copies, and any error messages if printing failed.

If a task ended up in <span style="color: #c0392b;">error</span> state, you can **reset** it, the task returns to <span style="color: #203671; font-weight: 600;">pending</span> and the print service will pick it up again.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>report-print-task.index.png</code><br>Report Print Task overview with status badges, printer and the reset action.
</div>

---

<h3 id="mailing" style="color: #203671; margin-top: 2.2em;">Mailing</h3>

A rendered document can be mailed as well as printed. Three sections work together, and all three behave like every other list view described above.

**Mailers** hold your SMTP accounts: host, port, credentials, sender address and the dispatch rate limits. The form has a **Test Mailer** button and a **Send test mail** action, the same idea as Test Connection on a Connection Config. A mailer has to be active before it is offered anywhere.

**Mail Templates** hold subject and body. The body is written in a built-in rich text editor, so no HTML knowledge is needed. A button opens the **placeholder catalog**, a searchable table of every token the template can use, each one copyable with a click. A preview shows the finished mail exactly as a recipient will see it, including the colours and the logo, which can be overridden per template.

**Mail Queue** lists every mail task with recipients, subject, attachments, mode and status. Opening one shows the mail that was actually sent, rendered in place. From there a mail can be **repeated**: a dialog lets you correct the mailer or the recipients before it goes out again, so a mail sent to the wrong address is fixed rather than cloned.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>mail-template.edit.png</code><br>Mail Template edit view with the rich text editor, the placeholder button and the whitelabel toggles.
</div>

Mailing itself is never configured here. It is requested per rendering, in the Generate PDF page, in the Scan2Print settings, in the mail dialog of a History Record, in a render job of the Job Scheduler, or in the `mailing` segment of a render request. The three sections above only provide the building blocks.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>mailing.history-record-modal.png</code><br>The mail dialog of a Report History Record with mailer, template, recipients and attachments.
</div>

<div style="border-left: 4px solid #5fc75d; background: #f6fdf6; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
ℹ️ Full detail is on the dedicated pages: <a href="/books/veloxfactory/page/report-mailing-sending-renderings-by-mail">Report Mailing</a>, <a href="/books/veloxfactory/page/mailers-master-data-for-your-smtp-accounts">Mailers</a> and <a href="/books/veloxfactory/page/mail-templates-subject-body-and-whitelabeling">Mail Templates</a>.
</div>

---

<h3 id="scheduling" style="color: #203671; margin-top: 2.2em;">Scheduling</h3>

Work that repeats has its own section. **Job Scheduler** lists every schedule with its type, its crontab expression, the next and the last run, and how that run ended. A **Run Log** button opens the full history of every run of every schedule, each with its trace id.

Creating a schedule starts with the type, a render job or the cleanup run, and the form follows from there. The expression is entered either in a guided mode with frequency, time and weekday pickers or as plain crontab syntax; both write the same field, and the next five run times are shown while you type. A render job additionally takes the report, an API token, the output and print settings, and the same parameter and data row tables as the Generate PDF page, here with a switch per field for entering a placeholder such as `[now.date]` instead of a fixed value.

**Run now** starts a schedule immediately without moving its next slot, which is how a new one is tried before it is switched on.

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>scheduler.overview.png</code><br>The Job Scheduler overview with type, cron expression, next run, last run and status per schedule.
</div>

<div style="border-left: 4px solid #5fc75d; background: #f6fdf6; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
ℹ️ Full detail is on the dedicated pages: <a href="/books/veloxfactory/page/the-job-scheduler-work-that-happens-without-you">The Job Scheduler</a>, <a href="/books/veloxfactory/page/render-jobs-a-render-request-with-a-clock-attached">Render Jobs</a> and <a href="/books/veloxfactory/page/the-purge-job-one-schedule-for-all-cleanup">The Purge Job</a>.
</div>

---

<h3 style="color: #203671; margin-top: 2.2em;">Users and API Tokens</h3>

User accounts are managed under the **Users** section, accessible to administrators only. Each user can hold one or more named API tokens, which grant API access under that user's identity.

From the user edit view you can:

- Create a new token and copy it immediately after generation (it is only shown once)
- Revoke any existing token with immediate effect

<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>user.edit1.png</code><br>User edit view, account data and API token management.
</div>

---
<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>user.edit2.png</code><br>User edit view, the permission sections.
</div>

---
<div style="border: 2px dashed #b8bfcc; background: #f7f8fa; padding: 18px 16px; margin: 16px 0; text-align: center; color: #525E5A;">
<strong>Screenshot placeholder:</strong> <code>create-token.modal.png</code><br>Create API token dialog, the token is shown once.
</div>


<div style="border-left: 4px solid #203671; background: #f0f3fb; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
⚠️ <strong>Copy your token immediately after creation.</strong> VeloxFactory only displays the token value once. If you lose it, you will need to revoke the old token and create a new one.
</div>

<h4 style="color: #203671; margin-top: 1.4em;">Permissions</h4>

Every user in VeloxFactory has a set of permissions that controls what they can see and do, both in the frontend and via the API. Since both use the same underlying controllers, **a permission that restricts an action in the frontend restricts the exact same action via API, and vice versa.** There is no way to grant API-only or frontend-only access to a resource.

Permissions fall into two categories: **global** and **per-resource**.

**Global permissions:**

| Permission | Effect |
|---|---|
| `global:admin` | Full access to everything, including user management |
| `global:use-api` | Allows use of the API and management of own API tokens |

**Per-resource permissions**, available for each of the following resources: `report-config`, `report-connection-config`, `report-context`, `report-history-record`, `report-print-task`, `report-mail-task`, `common-report-resource`, `printer`, `mailer`, `mail-template`, `scheduled-job`:

| Permission | Effect |
|---|---|
| `<resource>:full` | Full read/create/update/delete access to this resource |
| `<resource>:read` | View records only |
| `<resource>:create` | Create new records |
| `<resource>:update` | Edit existing records |
| `<resource>:delete` | Delete records |

`global:admin` always implies full access to all resources and overrides any per-resource setting.

`scheduled-job:*` also covers the run log. Changing or starting a render job is limited to its owner and to administrators, because it acts with the owner's permissions; reading it is not.

**Feature permissions:**

| Permission | Effect |
|---|---|
| `scan2print:use` | Access to [Scan2Print](/books/veloxfactory/page/scan2print-printing-labels-by-scanning). Implicitly includes `report-config:read`, `report-print-task:read` and `:create`, `report-history-record:create` and `:update` |
| `scheduled-job:create` | Creating a schedule means rendering, printing and mailing with it, so it implicitly includes `report-config:read`, `report-print-task:create`, `report-mail-task:create` and `report-history-record:create` and `:update`. `scheduled-job:full` does the same |

<div style="border-left: 4px solid #5fc75d; background: #f6fdf6; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
ℹ️ <strong>API token permissions are inherited from the user.</strong> A token does not have its own permission set, it acts with exactly the permissions of the user it belongs to. Revoking a token removes API access; the user's frontend permissions remain unaffected.
</div>

---

<h3 style="color: #203671; margin-top: 2.2em;">Frontend vs. API - What is the Difference?</h3>

The short answer: there is no feature difference. The frontend calls the exact same controller methods as the API. Everything you can do in the UI, you can also automate via API.

The frontend is optimised for interactive, human-driven workflows, exploring reports, reviewing history records, testing connections. The API is the right choice when you want to integrate rendering into external systems, automate repetitive tasks, or process results programmatically.

<div style="border-left: 4px solid #5fc75d; background: #f6fdf6; padding: 10px 16px; margin: 16px 0; border-radius: 0 4px 4px 0;">
ℹ️ Ready to explore the API? See <a href="/books/veloxfactory/page/meet-the-api">Meet the API</a> for authentication, query parameters, and a practical render example.
</div>

</div>