How to Export Metadata for Org Configuration Documentation in Salesforce
To export metadata for org configuration documentation, Salesforce admins typically need two different things: structural metadata (objects, fields, flows, permission sets, captured via the Metadata API or tools like Change Sets and sfdx) and file-level metadata (the attachments, PDFs, and documents tied to records, along with their owners and relationships). Most audits and migrations require both—and most native tools only give you one, badly.
Thank you for reading this post, don't forget to subscribe!This guide covers both sides of that picture, so you know exactly which approach to reach for depending on what “documentation” means for your project.
Two Different Kinds of “Metadata”—and Why the Distinction Matters
The word “metadata” gets used loosely in Salesforce conversations, and it’s worth being precise before picking a tool, because the two meanings point to completely different workflows.
Configuration metadata is the blueprint of your org: custom objects, fields, validation rules, flows, Apex classes, page layouts, profiles, and permission sets. This is what you’d pull for a technical audit, a sandbox refresh, or a change-management record. It lives in the Metadata API, and it’s typically retrieved through Salesforce CLI (sfdx/sf), change sets, or third-party DevOps platforms like Gearset or Copado.
Record and file metadata are different—it’s the data about your actual business records and the files attached to them: who owns a file, which Account or Case it’s linked to, when it was created, what format it’s in. This matters for compliance audits, storage cleanup, and migrations, but it’s a completely separate export path from schema metadata.
If your documentation need is “what does our org’s automation and data model look like,” you want the first. If it’s “what files exist, who owns them, and how do they connect to records,” you want the second. Many audits—SOC 2, ISO, and internal compliance reviews—end up needing both documented side by side.
Documenting Configuration Metadata (Schema, Flows, Permissions)
For structural documentation, native and semi-native options include:
- Salesforce CLI (sf/sfdx): Retrieves metadata as XML into a local project, which can be version controlled in Git. This is the closest thing to a real audit trail for configuration changes over time.
- Change Sets: Useful for moving metadata between orgs but not built for documentation — no readable export, no diffing.
- Setup Audit Trail: Shows the last 6 months of setup changes (or 2 years on Enterprise/Unlimited editions with add-ons), but it’s a change log, not a full configuration snapshot.
- Metadata API + custom scripts: Full control, but requires developer resources to build and maintain.
- Third-party DevOps tools (Gearset, Copado, Prodly): Purpose-built for this, with visual diffing and documentation exports, at an added licensing cost.
For most admins without dedicated DevOps tooling, SFDX retrieval into a Git repo is the most practical starting point—it’s free, it’s native, and it gives you a timestamped, diffable history.
Why Native Tools Fall Short for File-Level Documentation
Once you shift from schema to files and attachments, the native Weekly Export Service becomes the default — and it wasn’t built with documentation in mind. It hands you a single disorganized zip file with no clear structure, so linking any given file back to its parent account, contact, or custom object record means matching cryptic file IDs against separate CSVs by hand.
This creates three specific problems for anyone trying to produce clean documentation:
- No selective filtering — it’s all-or-nothing, so you’re exporting your entire file library even when the audit only needs a subset.
- Broken record relationships — file IDs aren’t matched to readable object names or record labels, so reconstructing “which file belongs to which record” takes manual VLOOKUPs.
- No ownership or object-type context — the metadata that actually matters for compliance (owner, record type, parent object) is stripped or buried in a separate file.
For a handful of files, that’s a nuisance. For an org with years of attachments across dozens of objects, it turns a one-afternoon audit task into a multi-day cleanup project.
How to Export File Metadata for Org Configuration Documentation
This is where a purpose-built export tool like a file downloader closes the gap. Here’s the practical workflow:
1. Start from the list view you already use. Open the relevant object (accounts, cases, or a custom object); apply the standard or custom list view that already filters to the records you care about; and export directly from that view—no separate query builder needed.
2. Run a targeted SOQL export for anything more specific. For date ranges, particular record owners, or custom field conditions, write a direct SOQL query against ContentVersion or Attachment:
SELECT Id, Title, FileExtension, OwnerId FROM ContentVersion WHERE IsLatest = true
This pulls exactly the file set you need instead of the entire org’s library.
3. Let the export generate its own documentation. Every bulk export automatically produces a CSV mapping file — sent straight to your inbox — that ties each file to its record ID, object type, and owner. That CSV is, in effect, your audit deliverable: a readable index of every exported file and where it came from, without building it manually in Excel.
4. Use the dashboard for the audit trail itself. Export history—who ran which export, how many files, and when—is tracked automatically. If an auditor asks, “How do you know your export process is controlled?” this is the answer: a visible, timestamped record of every export action.
5. Confirm the compliance layer. Because the export runs entirely within Salesforce’s platform—respecting existing permission sets and sharing rules and built on components that have passed Salesforce’s security review—you’re not introducing a new external data-handling risk into the audit itself.
Native Export vs. Purpose-Built File Export
| Export Capability | Native Weekly Export | files downloader |
|---|---|---|
| Selective Export | Org-wide only | Object, list view, or SOQL-based |
| Metadata Retention | Stripped or separated | Fully preserved with CSV mapping |
| Record Relationships | Required Manual Matching | Auto-mapped to parent records |
| Audit Trail | None built in | Dashboard with export history |
| File Format Support | Generic .dat structure | PDFs, .jpg, .png, docs, and more |
| Execution Time | Up to 48 hours queued | On-demand |
Best Practices for Org Configuration Documentation
A few habits make either type of export—schema or file-level—more useful when audit time actually comes:
- Document on a schedule, not just before an audit. Quarterly exports (of both metadata types) create a real history instead of a single snapshot that’s already stale by the time you need it.
- Version-control your schema metadata. Even a simple Git repo with SFDX retrievals gives you diffable history for free.
- Keep file-level exports segmented by object or business unit, rather than one giant export—it’s far easier to hand a specific slice to an auditor than to explain why a full org dump is relevant.
- Store the CSV mapping alongside the files themselves, not separately—the value of the mapping disappears if it gets detached from the export it describes.
- Treat storage-limit warnings as a documentation trigger, not just a cleanup task—archiving old attachments is also the moment to capture what’s being removed and why.