Docs/Reports & Invoices

Reports & Invoices

Reports show what is happening in the support desk: how many tickets came in, how quickly the team replied, whether SLA promises were met, which customers are using support heavily, and which finance items need attention. Invoices turn support contract and time-entry activity into finance workflows.

Analytics Page

The Analytics page lives at /reports. In plain language, it is the management dashboard for support work. A manager can open one report, choose a date range and filters, then read KPIs, charts, table rows, and action signals for the same slice of data.

Executive Operations Reports

/reports/operations-risk summarizes AI usage, knowledge gaps, inbound mail health, automation impact, recovery actions, security posture, deploy smoke, and operations readiness.
/reports/ai-trust summarizes AI action volume, failures, applied rate, review status, provider/model usage, and source-bound knowledge search activity.
Use these reports before buyer demos, release acceptance, and support leadership reviews.

Top Buttons

Button	What it does	Example	Who normally uses it
Freeze Snapshot	Saves the current report numbers so they can be reviewed later without recalculating live data.	Freeze the April SLA report before sending it to leadership.	Managers, team leads, finance reviewers.
Save Queue View	Saves the current report filters as a reusable ticket queue view.	Save a queue for all high-priority Acme tickets from this month.	Agents and leads who repeatedly work the same slice of tickets.
Scheduled Reports	Opens the schedule list where recurring report emails are created and managed.	Send a weekly PDF ticket volume report to the support lead.	Admins and users with report schedule permission.
Export PDF	Downloads the current report as a PDF file.	Attach the SLA compliance PDF to a monthly review email.	Anyone allowed to export reports.
Export Excel	Downloads the current report as an Excel spreadsheet.	Give finance the raw rows for deeper analysis.	Finance, operations, reporting users.

Analytics Tabs

Tab	Plain meaning	What you read there	Example use
Overview	The quick summary.	The first four KPI cards, filters drawer, shortcuts, and compact charts.	A support manager checks if ticket volume is rising this week.
Tables	The detailed rows behind the numbers.	Paginated report sections with wrapped text, linked rows, and metrics by date, category, agent, organization, or report-specific group.	An agent lead opens the exact tickets behind a spike.
Signals	The interpretation and next actions.	Narrative notes, forecasts, anomalies, and action buttons generated from the current report slice.	A manager checks what needs attention before a weekly meeting.

KPI Cards

KPI means key performance indicator. These are the big numbers shown first so a user can understand the report without scrolling through tables. The page shows four primary KPIs in the first row. Extra metrics are kept inside the Filters & shortcuts drawer so the page stays readable.

KPI item	Plain meaning	Example	How to use it
Total Tickets	How many tickets match the selected report and filters.	42 tickets from April 1 to April 30.	Use this to understand workload size.
Open Tickets	Tickets still waiting for work or closure.	12 open tickets for Acme Labs.	Use this to see backlog pressure.
Closed Tickets	Tickets completed in the selected slice.	30 closed tickets this month.	Use this to compare completion against intake.
Portal Tickets	Tickets created through requester or portal channels.	18 tickets submitted from the customer portal.	Use this to understand customer self-service activity.

The exact KPI names can change by report type. For example, an SLA report may focus on compliance and breaches, while an agent report may show assigned work, resolved work, or satisfaction.

Charts

Charts are visual helpers. They do not replace the tables; they make patterns easier to see. The current page uses compact mixed charts such as column plus line, because that shows both count and trend without taking over the whole page.

Chart	Plain meaning	Example	What to look for
Report Trend	Shows how the main report numbers move across dates or grouped rows.	Ticket count by day with a line for resolved count.	Spikes, drops, or steady growth.
Grouped Records / Distribution	Shows which group contributes the most, with a running total line.	Billing Issue, Bug Report, and Access Issue categories.	Which category or group is driving workload.
Current vs Previous	Compares this selected period with the previous matching period.	This month vs last month for total, open, closed, and portal tickets.	Whether the team is improving or load is increasing.

Analytics Filter Fields

Filters answer the question: "Which exact data should this report show?" A blank optional filter means "include everything for that field."

Field	What it means	Example value	What happens when you use it
Report	The type of report you want to read.	Ticket Volume	Changes the whole report: KPI labels, charts, tables, and signals.
Date From	The first day included in the report.	April 1, 2026	Only tickets or records from this date forward are counted.
Date To	The last day included in the report.	April 30, 2026	Only tickets or records up to this date are counted.
Category	Limits the report to one ticket category.	Bug Report	Useful when you only want to study one kind of issue.
Agent	Limits the report to one assigned internal user.	Nida Rahman	Useful for workload, performance, or coaching reviews.
Lead	Limits the report to tickets or accounts owned by a lead user.	Ammar Shah	Useful for lead accountability and escalation review.
Organization	Limits the report to one customer account.	Acme Labs	Useful for QBRs, contract reviews, and customer health checks.
Context Type	The type of linked business record attached to tickets.	Order, Asset, Subscription, Project	Use this before choosing a specific context record.
Context Record	The exact linked record inside the selected context type.	ORD-2026-1001 - Acme Labs	Shows only tickets tied to that specific order, asset, subscription, or similar record.

Filter Buttons

Button	What it means	Example
Apply Filters	Refreshes the report using the selected filters.	Choose Acme Labs and click Apply Filters to see only Acme data.
Reset	Clears filters and returns to the default report state.	Remove the Acme-only view and go back to all organizations.
Export PDF	Exports the currently filtered report to PDF.	PDF for a manager review meeting.
Export Excel	Exports the currently filtered report to Excel.	Spreadsheet for finance or deeper pivot-table analysis.

Report Types

Report type	Plain-language purpose	Example question it answers
Ticket Volume	Shows how much ticket work came in and how it moved through the queue.	Did support receive more tickets this week than last week?
Resolution Time	Shows how long tickets take to resolve.	Which categories take the longest to finish?
SLA Compliance	Shows whether response and resolution promises were met.	Are we breaching response commitments for urgent tickets?
Agent Performance	Shows agent-level workload and outcome information.	Who has too many open tickets or strong satisfaction feedback?
Lead Accountability	Shows ownership and lead-level follow-through.	Which lead owns overdue or escalated work?
Team Health	Shows operational pressure across the support team.	Is one team carrying more backlog than the others?
Organization Burn	Shows customer usage and support consumption.	Which account is using support fastest?
Agent Quality	Shows quality signals, not just ticket count.	Where do reopened tickets, feedback, or review signals point?
Finance & Aging	Shows finance-facing report signals such as invoice or aging visibility.	Which billing items need attention?
Contract Utilization	Shows support contract usage and coverage pressure.	Is a customer close to using their monthly support allowance?
Status & Incident Operations	Shows public status and incident-operation activity.	Are status components and incidents being handled cleanly?

Filters & Shortcuts Drawer

The Filters & shortcuts drawer keeps secondary controls out of the way so the page starts with KPIs. It can show schedule counts, saved report views, role packs, recent snapshots, overflow metrics, and the filter form.

Item	Plain meaning	Example
Schedules	How many report schedules exist.	3 total schedules.
Active	How many schedules are currently allowed to send emails.	2 active schedules.
Due Today	How many schedules are planned to run today.	1 schedule due today.
Saved views	Reusable report/filter shortcuts.	Executive Queue Health or Finance Pack.
Recent snapshots	Frozen copies of past report results.	April SLA Snapshot.

Scheduled Reports Page

The Scheduled Reports page lives at /report-schedules. It is used to send report files to internal users automatically. A schedule is not an instant email button. It is a rule that says: "At this time, generate this report with these filters and email it to these people."

Schedule List

Column	What it shows	Example	Why it matters
Schedule	The schedule name, report type, output format, and timezone.	Acme Weekly Volume Snapshot, Ticket Volume, PDF, Asia/Karachi	Identifies what will be sent.
Delivery	The daily or weekly timing plus next and last send times.	Weekly on Monday at 09:00. Next: 12 May 2026. Last: Never sent.	Shows when the email will run.
Recipients	The internal users selected to receive the report.	Admin, Nida Rahman, 2 configured recipients.	Shows who will get the attachment.
Status	Whether the schedule is active or inactive.	Active	Inactive schedules stay saved but do not send emails.
Actions	Edit or delete controls.	Pencil to edit, trash to delete.	Use edit for timing or recipient changes; delete to stop and remove the schedule.

Create/Edit Schedule Fields

Field	Plain meaning	Example value	Rules and effect
Schedule Name	A friendly internal name for this recurring email.	Acme Weekly Volume Snapshot	Required. Pick a name that tells users what the schedule sends.
Report Type	The report that will be generated and attached.	Ticket Volume	Choose any report type available on the Analytics page, such as Ticket Volume, SLA Compliance, Agent Performance, Finance & Aging, or Contract Utilization.
Format	The file type attached to the email.	PDF	Required. Choose PDF for reading, Excel for spreadsheet analysis.
Frequency	How often the schedule should run.	Weekly	Required. Daily runs once per day. Weekly runs once per week.
Run Hour (24h)	The hour of the day when the schedule should run.	9	Required. Use 0 to 23. 9 means 09:00, 17 means 17:00.
Weekday	The day used for weekly schedules.	Monday	Required only when Frequency is Weekly. Daily schedules ignore this field.
Timezone	The timezone used to understand Run Hour.	Asia/Karachi	Required. Use a valid PHP timezone such as UTC, Asia/Karachi, or America/New_York.
Date From	The start date saved inside the report filters.	April 1, 2026	Optional. If blank, the report service uses its default date window.
Date To	The end date saved inside the report filters.	April 30, 2026	Optional. If entered, it must be the same as or after Date From.
Category Filter	Limits the scheduled report to one ticket category.	Billing Issue	Optional. Blank means all categories.
Agent Filter	Limits the scheduled report to one assigned internal user.	Nida Rahman	Optional. Blank means all agents.
Organization Filter	Limits the scheduled report to one customer account.	Acme Labs	Optional. Blank means all organizations.
Context Type Filter	Limits the report by linked business record type.	Order	Optional. Choose this before choosing a Context Record.
Context Record Filter	Limits the report to one exact linked business record.	ORD-2026-1001 - Acme Labs	Optional. Requires a Context Type. The selected record must be valid for that context type.
Recipients	Internal users who will receive the scheduled report email.	Admin, Nida Rahman	Required. At least one user is needed. Users without email addresses are skipped at send time.
Active Schedule	Whether this schedule is allowed to send emails.	On	On means it can send when due. Off keeps the schedule saved but prevents delivery.

Schedule Buttons

Button	What it does	Example
Create Schedule	Saves a new recurring report rule.	Create a weekly PDF report for the support lead.
Save Changes	Updates the existing schedule settings.	Change the recipients or run hour.
Delete Schedule	Removes the schedule and stops future deliveries.	Delete an old report that is no longer needed.
Back to List	Returns to the schedule list without using the current form as an action.	Go back after reviewing a schedule.

How Scheduled Reports Reach Users

An admin creates a schedule and selects internal recipients.
The app calculates next_run_at from Frequency, Run Hour, Weekday, and Timezone.
Laravel's scheduler runs reports:send-scheduled hourly.
The command finds active schedules where next_run_at is due.
The app generates the report export using the saved filters.
The app emails the selected internal users with the PDF or Excel file attached.
The schedule is updated with last_run_at and the next future next_run_at.

Plain-language example: If Frequency is Weekly, Weekday is Monday, Run Hour is 9, Timezone is Asia/Karachi, and Recipients are Admin and Nida Rahman, the app prepares the selected report every Monday around 09:00 Asia/Karachi time and emails the attachment to Admin and Nida Rahman when the hourly scheduler checks due reports.

Important: Saving a schedule does not immediately send an email. It only saves the rule. Email delivery requires the Laravel scheduler, mail settings, and queue worker configuration to be working on the server.

Command and Server Setup

The command behind scheduled reports is reports:send-scheduled. It is not a web page button. It is a background command that must run on the server.

Item	Plain meaning	Example
Command	The Laravel command that checks due schedules.	`php artisan reports:send-scheduled`
Scheduler entry	The app calls the command hourly from Laravel's scheduler.	`Schedule::command('reports:send-scheduled')->hourly()`
Server cron	The operating system must wake Laravel's scheduler every minute.	`* * * * * cd /var/www/TicketPro && /usr/bin/php artisan schedule:run`
Queue worker	Needed when `QUEUE_CONNECTION` is database, Redis, or any async queue.	`php artisan queue:work --tries=3 --timeout=120`

Manual Test

Use this test after creating an active schedule with at least one recipient who has an email address:

cd /path/to/TicketPro
php artisan reports:send-scheduled

If a report is due, the command prints a sent count. If it prints Sent 0 scheduled reports., check whether the schedule is active, next_run_at is in the past, recipients have email addresses, and the date/time is correct for the selected timezone.

VPS Setup

SSH into the server.
Go to the app folder and confirm the command works: php artisan reports:send-scheduled.
Find the PHP binary with which php.
Edit cron with crontab -e for the deployment user.
Add the Laravel scheduler cron:

* * * * * cd /var/www/TicketPro && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

Use the real project path and PHP path for the server. This one cron entry also runs SLA checks and ticket automations, so do not remove it after scheduled reports start working.

If the hosting setup cannot run Laravel's scheduler and you only need scheduled reports, use this direct hourly fallback:

0 * * * * cd /var/www/TicketPro && /usr/bin/php artisan reports:send-scheduled >> /var/www/TicketPro/storage/logs/scheduled-reports.log 2>&1

The direct fallback does not run SLA checks or ticket automations. Use schedule:run whenever possible.

Shared Hosting Setup

On cPanel, open Cron Jobs and add a command like this:

/usr/local/bin/php /home/USERNAME/TicketPro/artisan schedule:run >> /home/USERNAME/TicketPro/storage/logs/cron.log 2>&1

Set the timing to every minute if available. If the host only allows every 5 or 15 minutes, use the shortest option. The report can be late by that much, but it should still send after the cron runs.

Direct shared-hosting fallback for scheduled reports only:

/usr/local/bin/php /home/USERNAME/TicketPro/artisan reports:send-scheduled >> /home/USERNAME/TicketPro/storage/logs/scheduled-reports.log 2>&1

On Plesk, create a Scheduled Task, choose "Run a command", and use the same absolute PHP path plus the absolute artisan path.

Do not expose this command as a public URL. If a shared host cannot run cron, ask the host to enable cron or move the app to a VPS. A public web route for background commands can be abused unless it is protected very carefully.

Production Checklist

Check	Why it matters	Example or fix
`APP_URL`	Links inside emails need the correct live URL.	`APP_URL=https://support.example.com`
Mail settings	Reports are delivered by email.	Set `MAIL_MAILER`, host, port, username, password, encryption, and `MAIL_FROM_ADDRESS`.
Queue worker	Queued notifications will sit in the queue until a worker runs.	Use Supervisor, systemd, hosting worker, or `php artisan queue:work`.
Cron logs	Shows whether the server is actually running the scheduler.	Temporarily log to `storage/logs/cron.log`.
Operations heartbeat	Confirms the app saw the command run.	Operations Center should show a recent `reports:send-scheduled` heartbeat.
Recipient emails	Users without email addresses are skipped.	Open Team Directory and confirm each recipient has an email address.

Troubleshooting Delivery

Symptom	Likely reason	What to check
`Sent 0 scheduled reports.`	No active schedule is due yet.	Check Active Schedule, `next_run_at`, Frequency, Run Hour, Weekday, and Timezone.
Command runs but no email arrives.	Mail or queue is not processing.	Check SMTP settings, spam folder, `storage/logs/laravel.log`, failed jobs, and `queue:work`.
Report sends at the wrong local time.	The schedule timezone or server timezone is misunderstood.	Use a PHP timezone such as `Asia/Karachi` and remember Run Hour uses 0 to 23.
Shared hosting sends late.	The host does not allow every-minute cron.	Use the shortest cron interval available or move scheduling to a VPS.
Operations heartbeat is stale.	The scheduler cron is not running.	Run `php artisan schedule:run` manually and fix the server cron path.

Invoices

/invoices lists finance workflows.
Draft invoices can be generated from support contracts.
Invoice detail supports board movement, workflow actions, adjustments, disputes, and export to PDF or XLSX.
Time entries, support contracts, line item sources, rates, and overages feed invoice calculations.

Adjustments and Disputes

Invoices can receive adjustment requests and dispute records. Adjustments can be approved or rejected, and disputes can be resolved. These workflows preserve finance accountability and keep billing decisions attached to the invoice.

Recommended Controls

Limit report export permission to trusted users.
Use export approval for sensitive organizations when required by governance policy.
Review report schedules after user changes so inactive users are not still recipients.
Validate billable hourly rates, internal cost rates, and overage rates on contracts before drafting invoices.