Data Export — request and download a ZIP

Open Admin portal → Data Export when an organisation needs a portable copy of its Farmlync records. The page creates a ZIP containing CSV files and a manifest. It is useful for data review, migration, audit preparation and an organisation’s own retention process.

Only a Tenant Admin or Platform Admin can view export history, request an export or download a completed file. A Platform Admin must first select the intended customer organisation. Confirm that tenant before every request because the archive can contain records from all its farms.

Handle the archive as customer data

The downloaded ZIP can contain animal, production, health, inventory and user information. Store and share it according to the organisation’s data-handling rules.

Page controls

Control	What it does
Export scope	Chooses All farms (tenant-wide) or one farm in the selected organisation.
Export my data	Creates a new asynchronous export request. It does not immediately download a file.
Export history table	Shows the request time, scope, processing status, non-empty entity-file count, ZIP size and expiry time.
Download	Downloads a completed, unexpired ZIP. It appears only for a ready export.
Page controls	Move through export history in fixed pages of 25 requests.

Request an export

1. Confirm the organisation shown in the Admin portal.
2. Open Data Export.
3. Set Export scope:
   • All farms (tenant-wide) includes farm-scoped records from every farm in the organisation.
   • Selecting a named farm restricts farm-scoped files to that farm.
4. Select Export my data.
5. Wait for the success message: Export requested — your ZIP will be ready in a few minutes. This confirms only that Farmlync accepted the request.
6. Follow the request in the history table until its status becomes Ready.

The scope defaults to All farms (tenant-wide). Farmlync loads every page of the organisation’s farm list, so a farm is not omitted merely because the organisation has more than 100 farms. A farm-scoped export still contains the organisation-wide identity_users.csv; its identity rows are not restricted to the selected farm.

Farmlync intends to permit one Pending or Processing export per organisation. While an in-flight request is visible on the current history page, the button reads Export in progress… and is disabled. The server normally rejects another request even if the in-flight row is on another history page or another administrator requested it. Two administrators submitting at the same instant are not yet protected by a database uniqueness/locking backstop, so check history rather than assuming only one request was admitted.

There is no date-range or file-format selector. A request exports the records available to the registered export sources when the background job runs.

What the ZIP contains

The current archive contains one CSV for each registered source, even when that CSV has no data rows:

• animals.csv
• treatments.csv
• milk_records.csv
• milk_lab_results.csv
• breeding_services.csv
• animal_events.csv
• stock_transactions.csv
• feeding_events.csv
• farms.csv
• identity_users.csv

The ZIP root also contains manifest.json. For every CSV, the manifest records its file name, entity name, schema version and row count. It also records the tenant ID, optional farm ID, export ID and export timestamp. Use the manifest to establish what a particular archive actually contains; do not rely on an older archive’s file layout because individual CSV schema versions can change.

CSV files use UTF-8 with a byte-order mark and RFC 4180 escaping, so commas, quotes and line breaks in values remain valid CSV. The Entities value in the history table is the number of CSV files that contain at least one data row. It is neither the number of ZIP entries nor the total number of exported records.

Read the history table

Column	Meaning
Requested	When the request was created, shown using the farm date/time display format.
Scope	All farms or the selected farm name. If the farm name is unavailable, Farmlync shows a shortened farm ID.
Status	The current state described below.
Entities	Count of entity CSV files with one or more rows. A dash means processing has not supplied the value.
Size	Completed ZIP size in B, KB or MB. A dash means no completed file size is available.
Expires	When the completed download stops being available.

The table displays these statuses:

• Queued — the request is waiting for the background processor.
• Processing — Farmlync is collecting CSV rows and creating the ZIP. The action column shows Working….
• Ready — the archive completed and Download is available.
• Failed — the job did not create a downloadable archive. Hover or focus the warning icon to read the recorded failure reason, then request a new export after the cause is resolved.
• Expired — the intended state after the seven-day download period ends. The current backend blocks the download after expiry but does not run the promised status/file cleanup, so a row can remain Ready and still return a not-found/expired error. Request a new export in that case.

When a Pending or Processing row is visible on the current page, Farmlync refreshes that page every ten seconds. You do not need to reload the browser manually.

Download and verify an export

1. Find a row with Ready status.
2. Recheck its Scope before downloading.
3. Select Download. The browser downloads a .zip file whose name begins with farmlync-export-.
4. Open manifest.json first.
5. Compare its farm ID, file list and row counts with the intended request.
6. Inspect the relevant CSV files before treating the archive as evidence of a particular dataset.

Downloads remain available for seven days after completion. After expiry—or if the stored file can no longer be found—the existing link cannot restore it; request a new archive. The present self-hosted storage implementation keeps the ZIP on the API instance’s local disk and has no active expiry sweep. Do not use the history status as proof that an expired file was physically erased until that retention worker is implemented.

Troubleshooting

Export my data is disabled

• Wait for the current Pending or Processing export to finish.
• Check other history pages if the current page does not show the in-flight request.

The requested farm is not in the selector

• Confirm that the Platform Admin selected the correct organisation.
• Confirm that the farm still belongs to that organisation.
• Reload the page after a newly created farm becomes available.

The request fails immediately

• Confirm that your current Farmlync role is Tenant Admin or Platform Admin.
• Confirm that a selected farm belongs to the current organisation.
• Check for another in-progress export.

A history row is Failed

• Read the warning icon’s failure reason.
• Resolve the reported issue and submit a new request. A failed row never gains a Download button.

A Ready row returns not found or expired

• Check whether its displayed expiry time has passed; the current history row may not have transitioned to Expired.
• If it has not passed, the local file may be unavailable on the API instance serving the download. Contact support and request a replacement archive.

The downloaded archive seems incomplete

• Check manifest.json rather than the Entities count alone.
• Remember that Entities counts non-empty CSVs, not rows.
• For a farm-scoped request, expect farm-scoped files to contain only that farm while identity_users.csv remains organisation-wide.
• Confirm that the expected data belongs to one of the currently registered CSV sources listed above.

Do not treat a queued or processing request as a completed export, and never share an archive until its scope and manifest have been checked.