Import and Export

Import and Export is a shared operating pattern across much of Holy Resource. You will see it on module tables where teams need to move data in or out without leaving the page.

This guide explains the real workflow behind the Data or module import/export button: what formats are supported, what checks run before import, how smart header mapping works, and what happens when you export to CSV, Excel, PDF, or Print.

It is also important to understand what this workflow is not. A normal table import or export is an in-app data operation. It is not the same thing as restoring a backup, replacing a workspace, or re-establishing trusted storage state.

If you need a full-database restore, a reviewed SQLite import, or rollback after a failed upgrade, go to Settings → General → Maintenance or use Recovery Mode if the app is already blocked there. The shared table import/export button does not replace those workflows.

That distinction matters because ordinary CSV or Excel imports should not, by themselves, trigger workspace integrity recovery behavior.

Where You Will See It

This pattern appears on many list pages across the app, including people and operations tables where teams commonly need:

• spreadsheet exports
• printable summaries
• data migration from another system
• cleanup imports after bulk edits
• one-time onboarding imports for a branch

The exact required columns vary by module, but the operating pattern is shared.

What the Shared Button Can Do

Depending on the module and your permissions, the shared button can offer:

• Export as CSV
• Export as Excel
• Export as PDF
• Print
• Import Data

Some pages expose export only, some import only, and some both. The available actions depend on how that page is configured and whether your account has import or export permission for that module.

Permissions and Access

Holy Resource checks permissions before it allows import or export work to start.

• If you do not have export permission, export actions are blocked.
• If you do not have import permission, the import dialog cannot be opened.

This matters because import and export often involve sensitive church data, and the app treats those actions as operational permissions rather than casual UI controls.

Export Formats

Holy Resource supports four export paths.

CSV export

CSV is the best choice when you want a simple spreadsheet file for bulk editing, backups of filtered table views, or migration into another system.

The export logic:

• uses the headers and rows supplied by the page
• wraps complex cell values safely when needed
• downloads a .csv file immediately in the browser or desktop runtime

Excel export

Excel export creates a .xlsx workbook and applies a little structure automatically:

• header row styling
• auto-sized columns
• a single sheet named Data

This is useful when your team wants a cleaner working spreadsheet without manual formatting first.

PDF export

PDF export is useful for sharing a frozen copy of a filtered table with leaders, boards, or admins who do not need an editable spreadsheet.

The PDF output includes:

• an optional title
• generation timestamp
• formatted table output with wrapped cells
• alternating row shading for easier reading

Print

Print opens a printer-friendly table layout using an internal iframe-based print flow instead of a popup window.

This is designed to work reliably across desktop and web platforms without being blocked by popup blockers.

Export Safety Details

Before export files are created, Holy Resource sanitizes spreadsheet-style cell values that could be interpreted as formulas in spreadsheet software.

This is especially important when exporting user-provided text. If a value starts with characters commonly treated as spreadsheet formulas, Holy Resource prefixes it safely before export.

That reduces the risk of spreadsheet formula injection when files are opened later in Excel-compatible tools.

Import File Types

The shared import flow accepts:

• .csv
• .xlsx
• .xls

When importing Excel files, Holy Resource reads the first worksheet only. When importing CSV files, it parses the header row and then maps remaining rows into objects using those headers.

CSV parsing is designed for real spreadsheet exports, not only hand-made flat files. That means the import flow handles:

• quoted values
• escaped quotes inside a value
• line breaks inside quoted cells
• common Windows and spreadsheet line endings
• UTF-8 BOM-prefixed CSV files

If the file type is not supported, the import is blocked before preview.

File Limits and Guardrails

The import dialog applies client-side safety limits before a file can proceed.

Current limits include:

• Maximum file size: 5 MB
• Maximum rows: 50,000
• Maximum columns: 300

If a file exceeds those limits, Holy Resource stops the import early and shows an error.

This is intentional. It protects both the app experience and the device from very large accidental uploads.

Import Flow At A Glance

Required Columns and Templates

When a module defines required columns, the import dialog shows them clearly near the top of the screen.

This helps the team answer two questions immediately:

• Does our file have the right structure?
• If not, can we download a template and fix the source file first?

The built-in template download gives you a blank CSV with the module's required headers already prepared.

For most teams, this is the safest starting point:

1. Download the template.
2. Keep the header row exactly as provided.
3. Add one record per row.
4. Save as CSV or Excel.
5. Re-import and verify the preview before confirming.

Security-First Import Checks

Holy Resource treats imports as a controlled operation, not just a file picker.

The shared dialog includes a security-first import panel and applies checks such as:

• required column validation when configured
• file size limits
• row and column limits
• PII warning scan on sample rows

The PII scan looks for likely patterns such as:

• email addresses
• phone numbers
• street-style addresses

It does not block the import by itself, but it warns the user that the file appears to contain sensitive data.

What Import and Export Does Not Do

Routine module import/export does not replace the trusted workspace and does not act like a restore operation.

That means a normal table import or export should not be treated as any of the following:

• a backup restore
• a database replacement
• a church migration event
• a workspace trust reset
• an integrity re-acceptance event

If your team is importing rows into a module such as members, attendance, finances, volunteers, or inventory, the shared flow is operating on structured table data inside the running app. It is not supposed to trigger integrity enforcement just because a file was chosen.

If integrity recovery appears during an ordinary table import, treat that as abnormal and investigate rather than assuming it is expected behavior.

Smart Import

Smart Import is designed to reduce friction when file headers do not exactly match the module's expected column names.

Offline smart matching

The first smart pass runs locally and can:

• match common alias names
• normalize header spelling differences
• infer some columns from data values

This is useful for files from older systems, hand-maintained spreadsheets, or inconsistent exports.

Hands-off mode

Hands-off mode allows Holy Resource to automatically run:

• offline header matching
• on-device value inference
• optional AI fallback when enabled

This is helpful when you want the app to do as much safe cleanup as it can before you review the preview.

AI Smart Import

AI Smart Import is optional. When enabled, Holy Resource can ask your configured AI provider to suggest a safe header map.

Important behavior:

• it maps headers only
• it does not rewrite row data
• it can optionally send redacted sample rows to improve mapping suggestions
• it may still fail or leave ambiguous fields unmapped

If AI Smart Import cannot determine a safe mapping, the import remains in your control and you can still proceed manually or fix the source file first.

Best-effort import

Best-effort import is a separate option that adds missing required columns as blank values so the file can continue through the flow.

This can help with messy historical exports, but it should be used carefully because it allows incomplete rows to proceed.

Best-effort mode should be treated as a recovery convenience, not the normal path for clean operational imports. If your team can fix the source file first, that is usually safer than pushing many blank required columns through import and cleaning up later.

Preview and Import Report

After a file is processed, Holy Resource shows a preview table of the first rows that will be imported.

The preview helps the user verify:

• the effective header names
• whether the rows still look structurally correct
• whether any columns were added or remapped

Alongside the preview, the Import Report can show:

• original file headers
• final headers after smart mapping
• row count
• mapping source (offline, ai, or none)
• warnings
• required columns filled as blanks through best-effort mode

Treat the preview and report as a checkpoint, not decorative UI. They are the main place to catch:

• a shifted column caused by a bad source export
• unexpected blank columns
• the wrong branch-specific file
• a header mapping you do not actually want
• signs that the source spreadsheet still needs cleanup

The report can also be downloaded as JSON, which is useful for admin handoff or audit-style troubleshooting.

What Happens on Confirm Import

The shared import system validates the final effective data one more time before it calls the module-specific import handler.

That means:

• permission is checked again
• required columns are validated again
• best-effort blank columns are applied if that mode is on
• the module page then decides how rows are actually written into the database

So the shared system handles the file safety and structure workflow, while the module itself handles the final business logic.

CSV and Excel Parsing Details

Holy Resource parses CSV rows with support for quoted values, including escaped quotes inside cells.

It also supports quoted multi-line cells, which is important when source spreadsheets contain notes, addresses, or free-text descriptions that span more than one line.

For Excel files, the first sheet is converted into rows using the first row as headers. Blank cells are normalized into empty strings so the final row shape stays predictable.

These details are easy to miss, but they matter because they keep imports stable even when source files are not perfect.

They also explain why two files that look similar in Excel can behave differently during import. One may be a clean structured export, while the other may contain hidden formatting differences, extra line breaks, or header problems that only become visible during parsing.

Common Import Problems To Catch Early

Before confirming an import, actively look for these issues:

• headers that were renamed by hand and no longer match the template
• duplicate-looking columns with slightly different spelling
• notes or address cells that contain embedded line breaks
• rows copied from another branch or church export
• blank required columns introduced by best-effort mode
• an Excel file where the real data is not on the first sheet

If the preview looks wrong, stop there. Fix the source file first instead of assuming the import will sort itself out later.

When To Use Each Export Type

• Use CSV for editing, cleanup, migrations, and lightweight backup slices.
• Use Excel when your team wants a nicer spreadsheet immediately.
• Use PDF when you need a frozen, shareable document.
• Use Print when a physical working copy is the goal.

Recommended Operating Workflow

1. Filter the table first if you only need a subset of records.
2. Export before a major cleanup so you have a working copy.
3. Use the template download before first-time imports.
4. Keep the header row unchanged whenever possible.
5. Review Smart Import notes instead of assuming they are always correct.
6. Treat best-effort import as a recovery tool, not the default path.
7. Download the Import Report when the import is important or messy.
8. If the app ever enters integrity recovery during a normal table import, stop and investigate because that is not the intended workflow.

Common Good Habits

• Keep source headers simple and consistent before importing.
• Review the preview even if Smart Import says it fixed everything.
• Avoid importing oversized spreadsheets when smaller module-specific files will do.
• Prefer CSV for first cleanup work and Excel for handoff work.
• Export a filtered copy before destructive bulk cleanup.