“Connect reporting to data” sounds like a setup task. In production, it’s an architecture decision that determines:
- what your users trust (data freshness and correctness)
- what your security team approves (blast radius and access boundaries)
- what your ops team can support (reliability and monitoring)
This guide is a practical catalog of reporting integration patterns using CxReports: connecting to databases and APIs, embedding reports in apps, exporting PDFs, and operating safely at scale.
The integration problem: freshness, trust, blast radius
Before choosing tools, answer three questions:
- Freshness: do you need real-time, near-real-time, or is daily batch enough?
- Trust: where do you enforce business rules—upstream services, a reporting layer, or inside the report?
- Blast radius: if this integration breaks or leaks data, who is impacted (one user, one tenant, everyone)?
Most “reporting outages” are not rendering bugs. They’re integration failures:
- slow DB queries from production primaries
- missing parameters leading to empty reports
- schema changes breaking SQL
- expired tokens / wrong headers in API calls
- leaked secrets or over-broad database permissions
Integration surfaces in CxReports (what you can plug into)
CxReports supports multiple integration surfaces. Pick the smallest surface area that matches your needs.
1) Data sources inside reports
You can attach data directly to reports using multiple data source types:
- SQL queries
- API requests (GET/POST)
- JSON / CSV embedded data
- JavaScript computed sources (light transforms)
- MongoDB (JS-generated commands)
- Google Sheets directly fetching the latest state of the document
Docs: Data Sources
2) CxReports platform API
If you’re integrating reporting into another application:
- list reports and workspaces
- export PDFs via API (sync or async)
- push temporary data at render time
- use nonce tokens for iframe embedding (client-side safe flow)
- starting and managing jobs for batch report generation and delivery
Docs: CxReports API
3) Data Agent (cloud ↔ private DB)
If you run CxReports in the cloud but need secure access to private databases, the Data Agent:
- establishes a websocket connection to CxReports
- executes DB queries without opening inbound database access to the Internet
Docs: Data Agents
4) Workspace portability (repeatable integrations)
To standardize integrations across environments and teams, you can export/import configuration:
- reusable data sources, themes, report types, page types, parameters, etc.
Docs:
Pattern catalog: choose the simplest that works
Below are the most common patterns we see in production reporting stacks. (These map well to common “event-driven vs scheduled vs hybrid” integration types described by integration platforms.)
Pattern A: SQL database query via Data Agent
Use when: you have stable schemas, clear ownership, and can enforce least privilege. Best for: internal reporting, operational dashboards, finance/ops reports against read replicas or warehouses.
How it works:
- Data Agent runs near your database (cloud or on-prem)
- CxReports connects outbound to the Agent to execute queries
- Create a SQL data source in CxReports
- Map report parameters into your query
- Render report pages from
$data.<sourceName>
Guardrails:
- Use read-only DB principals per workspace/tenant
- Avoid production primaries; prefer replicas or warehouses for heavy queries
- Set query timeouts and monitor slow queries
- Rotate keys/secrets and monitor Agent health
- Restrict which DBs and schemas the Agent can access
Docs:
Pattern B: API aggregation layer → API data source in CxReports
Use when: your data lives across multiple services and you need consistent, versioned contracts.
Best for: multi-service SaaS, complex business rules, “one endpoint per report section”.
How it works:
- Your app exposes reporting endpoints (e.g.,
/reporting/quarterly-summary) - CxReports API data source calls those endpoints
- The report remains stable even if internal services change
Guardrails:
- Version endpoints (
/v1/…) and support backward compatibility - Cache expensive queries; enforce rate limits
- Treat reporting endpoints as production APIs (SLOs + monitoring)
Docs:
Pattern C: Push render-ready data at call time (Temporary Data)
Use when: personalization is per-user/per-request, or you want to precompute complex joins upstream. Best for: “download your statement” flows, customer portals, on-demand PDFs.
High-level flow:
- Your backend fetches/joins data from internal systems
- Your backend calls CxReports
temporary-dataendpoint with a data object - The report uses that temporary object during rendering
- Export PDF via API
Guardrails:
- Keep payloads bounded (size limits, pagination strategy)
- Define retention/PII rules (temporary data still needs governance)
- Log correlation IDs for auditability
Pattern D: File snapshots (CSV/JSON) for reconciled reporting
Use when: you need a deterministic snapshot (audit/reconciliation), or sources are not queryable reliably. Best for: end-of-period statements, regulated reports, “frozen” audit evidence.
How it works:
- Upstream job produces a JSON/CSV snapshot
- CxReports ingests that snapshot as a data source
- Output is deterministic for that snapshot version
Docs:
Guardrails:
- Include snapshot metadata (timestamp, version, inputs)
- Manage retention and access rules
Pattern E: Computed sources inside CxReports (JavaScript data sources)
Use when: transforms are light and deterministic.
Best for: small aggregations, combining multiple sources, formatting helper objects.
Guardrails:
- avoid heavy computation in-report; precompute upstream
- keep transforms testable and deterministic
Execution models: event-driven vs scheduled vs hybrid
Integration platforms commonly describe four high-level integration types:
- Event-driven (webhooks/publish-subscribe)
- Scheduled (batch/recurring)
- Synchronous (request/response waiting for completion)
- Hybrid (mix patterns)
For reporting, the practical mapping is:
- Scheduled: nightly refresh, weekly executive packets, quarterly statements
- Event-driven: generate a PDF when an invoice is paid, or when a deal closes
- Hybrid: nightly snapshot + on-demand personalization
Embedding and delivery patterns (how users consume reports)
Pattern G: Embed report previews in your app (iframe with nonce tokens)
If you need in-app previews, avoid putting long-lived tokens in the browser. Instead:
- create a nonce token server-side
- pass
nonce={value}for iframe authentication (token becomes a cookie on first request)
Docs:
Pattern H: Server-side PDF generation (API export)
For “Download PDF” or scheduled exports, use the API endpoints for PDF export and return the file from your backend.
Pattern I: Email delivery
If you deliver reports by email, treat it as part of the integration surface:
- configure SMTP and domain restrictions where needed
- ensure secure handling of recipients and bounces
Docs:
Pattern J: Google Drive upload
When generating large batches of reports via jobs, the individual reports can be uploaded to a pre-configured Google Drive. Once all reports are uploaded, a consolidated report can be created from the individual files.
Operational checklist (don’t ship without this)
Security
- ✓ Least-privilege DB roles per workspace/tenant
- ✓ Store secrets in a proper secret store; rotate them
- ✓ Define PII/PHI rules for temporary data and snapshots
- ✓ Keep PATs server-side; use nonce tokens for client embedding
Reliability
- ✓ Retries with backoff for API data sources (and upstream services)
- ✓ Timeouts and circuit breakers for reporting endpoints
- ✓ Idempotency for scheduled jobs (avoid duplicate sends)
Performance
- ✓ Prefer read replicas/warehouses for heavy reporting
- ✓ Cache aggregation endpoints
FAQ
What’s the best integration pattern for embedded reporting?
Start with server-side PDF export for production reliability, and add iframe embedding for interactive previews when needed (nonce token flow).
Should CxReports query our production database directly?
CxReports uses a Data Agent to query databases. The agent should have read-only access and be securely managed. Make sure query limits, timeouts, and resource usage are configured on both the database and the CxReports data sources to avoid impacting production systems.
When should we push temporary data instead of querying directly?
When the report needs request-specific personalization or when joins/transformations are expensive and better done upstream.
Next steps
If you want help choosing the right integration pattern for your reporting:
- list your report families (executive, customer, compliance)
- define freshness + trust requirements per family
- pick the simplest integration pattern and add guardrails
We can run a 45-minute architecture review and leave you with a recommended pattern set and a rollout plan.