Report Packs Asset Tickets Developer Guide

Report Packs: assets and their tickets — Developer Guide

5.2.0 · #310 · User guide: Report Packs · Engine: Report Packs Developer Guide

🔑 The one-line version

Three handlers in includes/report_packs/blocks_asset_tickets.php read ticket_assets (the link a ticket's asset picker writes). They choose their tickets through the ticket blocks' own rpTicketWhere(), so a pack counts only tickets the person it is built for could open.

📁 Files

File	What
includes/report_packs/blocks_asset_tickets.php	rpAssetTicketsKpis(), rpAssetTicketsList(), rpAssetTicketsBreakdown(), the guard rpAssetTicketsGuard(), RP_ASSET_TICKET_DIMENSIONS, RP_ASSET_NAME_SQL
includes/report_packs/blocks.php	Handlers assets.tickets_kpis, assets.tickets_list, assets.tickets_breakdown; six toolbox items in the Assets area (below)
lang/en/reporting.php	packs.asset_tickets.*, packs.tool.assets_tickets_*, and the Assets area's help text
includes/feature_bingo/cards/assets.php	Card assets.tickets_report_pack
tests/report-packs-asset-tickets.php	14 checks against seeded data

🧰 One handler, several blocks

The toolbox items are presets of the three handlers. A block can be turned into its neighbour by changing an option, as everywhere in Report Packs:

Toolbox item	Handler	Preset
Assets and tickets summary	assets.tickets_kpis	-
Assets with the most tickets	assets.tickets_list	sort count, limit 10
Every asset with tickets	assets.tickets_list	sort name, limit 500
Asset tickets by model	assets.tickets_breakdown	by model, hbar
Asset tickets by type	assets.tickets_breakdown	by type, doughnut
Asset tickets by category	assets.tickets_breakdown	by category (the ticket's top-level category), hbar

Every handler also has basis: tickets created in the period, closed in it, or open at its end - the same option, with the same meaning, as the ticket blocks.

🔒 Which tickets - never re-implement the scope

[$where, $p] = rpTicketWhere($conn, $analystId, $o['basis'], $range, $tenant);
// WHERE t.deleted_datetime IS NULL
//   + the pack's company        (rpTenantClause on t.tenant_id)
//   + the department rule        (ticketDepartmentScopeSql - 5.1.0)
//   + created / closed / open    (the basis)

• 🔑 The company is the ticket's, not the asset's.
• Binned tickets are left out.
• The handler's module is assets. Because these blocks show ticket counts, rpAssetTicketsGuard() also refuses a viewer without Tickets, using the same message as a missing module.

🔢 Counting

-- per asset (the table): a ticket on two assets counts once for EACH asset
SELECT a.id, ..., COUNT(*) AS n
  FROM tickets t JOIN ticket_assets ta ON ta.ticket_id = t.id JOIN assets a ON a.id = ta.asset_id
 $where GROUP BY a.id ORDER BY n DESC, name

-- per group (the charts): ONCE per group - two laptops of one model on one ticket
-- are one ticket for that model
SELECT <label> AS label, COUNT(DISTINCT t.id) AS value ... GROUP BY label

• The summary's share is the period's tickets that name an asset, out of all the period's tickets (both through the same $where).
• An asset's name is its hostname, else its asset tag, else #id (RP_ASSET_NAME_SQL). The tag is shown underneath when it differs from the name.
• Retired assets are kept in the counts and marked Retired: a retired laptop's tickets are still part of the history.
• Model is CONCAT_WS(' ', manufacturer, model), so the same model from two manufacturers stays apart.

⚠️ Traps

• TRAP: choose tickets with rpTicketWhere(), never a fresh WHERE. Otherwise the department rule from 5.1.0 is lost, and a pack counts tickets its reader may not open.
• TRAP: COUNT(DISTINCT t.id) in the charts. A plain COUNT(*) counts a ticket once per linked asset, so a model's figure rises with the number of laptops on one ticket.

🧪 Tests

• tests/report-packs-asset-tickets.php (14, prtest only). It seeds three assets and seven tickets in March 2001, in a rolled-back transaction, and checks:
  • the per-asset counts and their order;
  • that a ticket before the period, and a binned one, are not counted;
  • the limit note, and the column switches;
  • "By name";
  • the model chart counting the two-laptop ticket once;
  • manufacturer, ticket category, type and location;
  • the summary: 4 tickets, 80%, 3 assets, the busiest named.
• tests/report-packs-blocks.php (48, read-only) runs all three handlers with every option, as part of the whole registry.

---

See also: Report Packs Developer Guide · Asset tickets