Reports and Exports

Reports and Exports

The Reports module builds read-only fleet reports from Jamf Pro computer and mobile inventory. It plans queries, loads inventory through the shared gateway, normalizes heterogeneous payloads, aggregates records, renders visual summaries, and exports multiple document formats.

Report Pipeline

flowchart TD
    Builder["ReportBuilderView"] --> Request["ReportRequest"]
    Request --> Validate["ReportsQueryPlanner.validate"]
    Validate --> Plan["ReportsQueryPlanner.makePlan"]
    Plan --> Service["ReportsInventoryService"]
    Service --> Cache{"Inventory cache warm?"}
    Cache -->|no| FetchComputers["Fetch computer pages"]
    Cache -->|no| FetchMobile["Fetch mobile pages"]
    FetchComputers --> Normalize["Normalize records"]
    FetchMobile --> Normalize
    Normalize --> Directory["Location directory enrichment"]
    Directory --> CacheStore["In-memory inventory cache"]
    Cache -->|yes| CacheStore
    CacheStore --> Filter["Client-side criteria matching"]
    Filter --> Aggregate["ReportsAggregator"]
    Aggregate --> DataSet["ReportDataSet"]
    DataSet --> Visuals["GeneratedReportView visuals"]
    DataSet --> Export["Export coordinator"]

Loading

Query Planning

ReportsQueryPlanner converts a user report request into:

• Selected inventory domains.
• Requested fields.
• Optional server-side filters where safe.
• Client-side filters for fields that are not reliably supported by Jamf server filtering.
• Validation errors for unsupported field/comparison combinations.

flowchart LR
    Request["ReportRequest"] --> Domain["Domain selection"]
    Request --> Fields["Field catalog lookup"]
    Request --> Criteria["Criteria list"]
    Fields --> Plan["ReportQueryPlan"]
    Criteria --> ServerFilter["Server filter when supported"]
    Criteria --> ClientFilter["Client-side filter fallback"]
    Domain --> Plan
    ServerFilter --> Plan
    ClientFilter --> Plan

Loading

Inventory Loading

Reports uses ReportsInventoryService, an actor that:

• Fetches all requested computer pages.
• Fetches all requested mobile device pages.
• Loads building and department directories for readable location fields.
• Normalizes computer and mobile payload variants into ReportDeviceRecord.
• Preserves confidence metadata for inferred device identity.
• Caches the inventory snapshot until explicitly invalidated.
• Emits diagnostics for load start, cache build, page count, unknown records, inferred records, and failures.

Aggregation

ReportsAggregator produces:

Aggregate	Purpose
Total device count	Top-level report population.
Counts by device type	Gauge segments and type summary.
Counts by model	Top model ranked bar chart.
Counts by location	Location ranked bar chart.
Counts by OS version	OS distribution view.
Storage buckets	Capacity/usage distribution.
Battery buckets	Battery health/level distribution.
Unknown count	Records that could not be confidently classified.
Inferred count	Records classified through inference rather than explicit model metadata.

Visualization Surface

flowchart TB
    Report["GeneratedReport"] --> Metrics["Metric cards"]
    Report --> Gauge["Device type segmented gauge"]
    Report --> Models["Top Models bar chart"]
    Report --> Locations["Locations bar chart"]
    Report --> Storage["Storage distribution meter"]
    Report --> Battery["Battery distribution meter"]
    Report --> Table["Sortable data table"]
    Report --> Confidence["Inferred/unknown identity notice"]

Loading

Export Formats

Format	Renderer
PDF	ReportPDFRenderer
CSV	ReportCSVRenderer
Markdown	ReportMarkdownRenderer
Text	ReportTextRenderer
Document	ReportDocRenderer

Export file names are built by ReportExportFilenameBuilder, and the SwiftUI file exporter receives a prepared ReportExportDocument.

Export Flow

sequenceDiagram
    participant User as Operator
    participant View as GeneratedReportView
    participant VM as ReportsViewModel
    participant Coordinator as ReportExportCoordinator
    participant Renderer as Format renderer
    participant Exporter as SwiftUI fileExporter

    User->>View: choose export format
    View->>VM: prepare export
    VM->>Coordinator: render(report, format)
    Coordinator->>Renderer: render bytes
    Renderer-->>Coordinator: data + content type
    Coordinator-->>VM: export document
    VM-->>View: prepared file
    View->>Exporter: present save panel
    Exporter-->>View: save result
    View->>VM: record completion

Loading

Read-Only Jamf Contract

Reports is read-only against Jamf Pro inventory. It consumes the shared gateway for authenticated reads and exports user-selected output locally. Report generation should not mutate Jamf Pro records.

Important Files

Path	Role
ForsettiApp/Modules/Reports/ReportsModule.swift	Feature composition root.
ForsettiApp/Modules/Reports/Services/ReportsInventoryService.swift	Inventory fetch, cache, normalization, and diagnostics.
ForsettiApp/Modules/Reports/Services/ReportsQueryPlanner.swift	Field validation and query planning.
ForsettiApp/Modules/Reports/Services/ReportsAggregator.swift	Aggregate calculations and gauge segments.
ForsettiApp/Modules/Reports/Models/ReportsFieldCatalog.swift	Field catalog and reportable field metadata.
ForsettiApp/Modules/Reports/Views/GeneratedReportView.swift	Visual report surface and export actions.
ForsettiApp/Modules/Reports/Export	Export format renderers and coordinator.