Custom Reports

Overview

Custom Reports let you create filtered views of your Customers, Jobs, Estimates, and Invoices. Describe what you want to see in plain language (e.g., "all overdue invoices over $500") and Forz uses AI to generate the Meilisearch filter query. You can also write filters manually. Reports display configurable columns and can be exported to CSV or PDF for sharing with stakeholders.

Before You Begin

Prerequisites:

1. You have the Custom Reports: Create permission on your role.

2. You have the Custom Reports: View permission to see existing reports.

Creating a Report

1. Click Reports in the sidebar navigation.

1. Click the + New Report button.

1. Select a Model — the type of data you want to report on.

2. Customer (customer records)

3. Job (job/work order records)

4. Estimate (estimate records)

5. Invoice (invoice records)

1. Enter a Description of what the report should show. Write this in plain language (e.g., "All jobs completed in the last 30 days with a total over $1,000"). This is required.

2. Click Save.

Expected result: Forz creates the report and begins processing. The AI filter generation runs in the background. After a few seconds, the report loads with filtered results. The report name is auto-generated from your description.

Note: The report enters a "processing" state while the AI generates the filter. The page automatically reloads when processing is complete.

How AI Filter Generation Works

When you create or update a report, Forz sends your description to the MeilisearchFilterService, which generates a Meilisearch filter query. The AI considers the available filterable attributes for your selected model and translates your natural language description into a structured filter.

For example, the description "overdue invoices with balance over 500" might generate:

status = "Overdue" AND balance > 500

If the generated filter has a syntax error, Forz detects the Meilisearch API error and automatically regenerates the filter.

Available Columns by Model

Each model has a set of columns you can display in your report. After creating a report, you can customize which columns appear.

Customer columns: number, status, organization, assignee, createdat, updatedat, statusupdatedat, labels.

Job columns: number, status, customername, jobtype, createdat, duedate, statusupdatedat, total, labels, cf1, cf2, cf3, cf4, cf_5.

Estimate columns: number, status, amount, customername, estimatedate, created_at, labels.

Invoice columns: number, status, amount, balance, customername, duedate, created_at, labels.

Filterable Attributes by Model

These are the attributes you can reference in your report description for filtering.

Customer: number, status, organization, assignee, city, state, createdat, updatedat, statusupdatedat, labels

Job: number, status, customername, jobtype, assigneename, duedate, createdat, statusupdated_at, total, labels

Estimate: number, status, amount, estimatedate, createdat, updatedat, statusupdated_at, labels

Invoice: number, status, amount, balance, customername, duedate, createdat, updatedat, statusupdatedat, labels

Customizing Report Columns

1. Open the report.

2. Click Edit Columns.

3. Add or remove columns from the available list. Columns that are already added are shown separately from columns not yet added.

4. Save your changes.

Expected result: The report table updates to show only the selected columns in the order you configured.

Editing a Report Filter

1. Open the report.

2. Click Edit.

3. Update the Description with your new filter criteria.

4. Click Save.

Expected result: Forz regenerates the filter in the background. The report re-enters the processing state and reloads with updated results when complete.

Regenerating a Report Filter

If a report's filter produces errors or unexpected results, you can force regeneration.

1. Open the report.

2. Click Regenerate.

Expected result: Forz marks the report as processing and re-runs the AI filter generation. The page reloads when the new filter is ready.

Exporting Reports

Export to CSV

1. Open the report with the results you want to export.

2. Click the CSV export option (or append .csv to the report URL).

Expected result: Your browser downloads a CSV file named [report-name]-[date].csv containing all matching records with the configured columns.

Export to PDF

1. Open the report with the results you want to export.

2. Click the PDF export option.

Expected result: A PDF document is generated and opens in your browser (or downloads, depending on your browser settings). The PDF uses a print-optimized layout.

Print View

1. Open the report.

2. Click Print.

Expected result: The report opens in a print-friendly layout (up to 1,000 records) suitable for browser printing.

What Happens After Creating a Report

When a report is saved, Forz automatically:

• Creates initial columns — all available columns for the selected model are added by default via the after_create :create_initial_columns callback.

• Queues AI filter generation — the CustomReportSetFilterJob runs in the background to generate the Meilisearch filter from your description.

• Sets the report name — the AI generates a concise report name based on your description.

• Sets a filter description — a human-readable summary of what the filter does.

Warning: Reports are soft-deleted (moved to the trash bin) when you delete them. The data they report on is not affected -- reports are read-only views of your existing records.

Common Scenarios

Tracking overdue invoices for collection follow-up

An office manager needs a list of all unpaid invoices past their due date.

1. Click Reports > + New Report.

2. Select Invoice as the model.

3. Enter the description: "All invoices with status Overdue".

4. Save. The AI generates a filter for overdue invoices.

5. Export to CSV and share with the collections team.

Weekly job completion report for management

A service manager wants to see all jobs completed in the past week for a status meeting.

1. Create a new report with model Job.

2. Enter the description: "Jobs completed in the last 7 days".

3. Save. Edit columns to show: number, status, customername, jobtype, total, statusupdatedat.

4. Export to PDF for the meeting.

Finding high-value estimates pending approval

A sales manager wants to identify estimates over $5,000 that are still pending.

1. Create a new report with model Estimate.

2. Enter the description: "Estimates with status Pending and amount greater than 5000".

3. Save. Review the results and follow up with customers.

Troubleshooting