> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/codev/development/data-packages.md).

# Data packages

A data package manages Salesforce records as files in your repository. Reference and seed data — country tables, pricing settings, configuration records — are versioned next to your source and moved between orgs with the same pull and push motions you use for metadata.

Data packages live under **Dev > My Workspace > Data Tracking**. The page lists every data package in your project as a file tree, with the git status of each file, and opens each file in a viewer suited to it. Workspace Explorer and Org Explorer link here through the **Data Packages** button.

## Creating a data package

Click **Create your first Data Package** (or run **Create data package** from the command palette). The dialog scaffolds the package: it registers a data package directory in your project and creates a starter `export.json` for you to fill in.

<figure><img src="/files/mMhaYRue37zZR22WhPYU" alt="The New data package dialog with a package name, folder location, and the per-record format checkbox"><figcaption><p>New data package — name, folder, and the storage format.</p></figcaption></figure>

The **per-record format** checkbox picks how records are stored:

* **Per-record** — each record is its own YAML file under `records/`, so changes show up as clean per-record git diffs and merge without conflicts. Large and rich-text field values are kept in a sidecar folder. This format is in beta.
* **Flat CSV** — one CSV file per object, the classic layout.

Pull and push behave the same in both formats, and a package can be converted between them later from its actions menu.

## Configuring what the package tracks

The package's `export.json` declares the objects to track: a query per object, the operation, and the external ID field used to match records between orgs. Opening `export.json` shows the configuration in three views — **Flow**, a diagram of the objects and the lookups between them; **List**; and raw **JSON**.

<figure><img src="/files/evWLIwkdRtPNSN1ioDZH" alt="The Data Tracking page with a data package selected and the Flow view showing Account and Contact connected by the AccountId lookup"><figcaption><p>The Flow view — each object with its operation and matching key, connected by lookup relationships.</p></figcaption></figure>

## Pulling and pushing records

The package's actions menu runs the data operations. Each opens with your target org preselected — you can pick any connected org, and the action runs in the background with the outcome delivered as a notification.

| Action              | What it does                                                                                                       |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Pull from org**   | Reads the queried records from the org and writes them into the package files.                                     |
| **Push to org**     | Upserts the package's records into the org, matching on each object's external ID.                                 |
| **Simulate push**   | A dry run of the push — validates record matching, lookups, and field mapping without writing anything to the org. |
| **Preview changes** | A read-only comparison against the org, listing the inserts, updates, and deletes a sync would make, per object.   |

Records flow through your normal source control from here: after a pull, the changed record files appear in [Source Control](/flxbl/codev/development/development-workflow.md#commit-your-work-source-control) to be committed and reviewed like any other change.

## Keeping the package tidy

The tree flags leftovers that tend to accumulate around data packages — flat CSVs left behind after a migration to per-record format, CSV files not declared in `export.json`, and empty record folders. The actions menu offers a clean-up for each, showing the affected files before deleting. **Add record…** creates a new record file in place, and the two **Convert** actions switch the package between per-record and flat CSV layouts.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/codev/development/data-packages.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.