> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reasonos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import Work from ReasonOS

> Preview an exported project's Work records, add missing records, or catch up supported fields from the source.

Use **Project settings → Work → Import from ReasonOS** to bring a ReasonOS
Work transfer file into a destination project. This is a one-way transfer,
with an explicit choice about whether to update records imported earlier.
[Import from Linear](https://docs.reasonos.com/platform/linear-import.md) is a separate flow.

## Choose a file and a mode

1. Get a JSON file prepared with the ReasonOS Work transfer tool from the
   source project's administrator. The file must be 32 MiB or less. This
   page accepts version 1 and version 2 files. Version 2 also records who
   closed each source cycle. This page imports an existing file; it does
   not export the source project.
2. Open the destination project's **Settings → Work → Import from ReasonOS**.
   You need permission to manage that project's settings and access to Work.
3. Choose the file, then choose the mode:
   * **Add new records** creates missing records and skips records already
     imported. It leaves existing records as they are.
   * **Catch up from source** also updates supported fields on previously
     imported issues and comments. The file wins over destination edits to
     those fields. Records created only at the destination remain, and
     nothing is deleted.

> [!NOTE]
>
> Choosing a file reads it in your browser. Previewing or starting an import
> sends the file to this destination workspace. The page never contacts the
> source installation or asks for its credentials.

Catch-up does not synchronize source deletions, initiative membership or
other unsupported changes. This page does not refresh an existing cycle's
name, dates or state, or close and start cycles. A skipped record is not proof
that its fields match the source. Read the item reasons before accepting a
transfer as a complete migration.

## Preserve cycle history during a migration

Preserving cycle history is a separate administrator operation, available only
when both deployments support it. Choosing **Catch up from source** in this
page does not enable it. An ordinary import of a version 2 file does not
restore the person who closed a cycle; read the cycle item outcomes for that
limitation.

Ask the administrator coordinating the migration for a fresh version 2 export
and a cycle-history preview. That operation preserves the source's exact cycle
dates, state, closure time, close resolutions and recorded closer. It keeps
destination cycle names and cadence. The closer must match exactly one
eligible destination member by email; a matching display name or numeric ID
is insufficient. Missing or ambiguous matches refuse the history change.
Version 1 files cannot restore closed-cycle history because they omit the
closer.

Issue catch-up happens before the cycle-history transaction. If the history
change is refused or rolled back, its cycle and close-resolution changes are
not applied, but earlier issue changes remain. A cycle the run created stays,
planned. Read the run's history notice
and item outcomes. Existing conflicting closed history is refused rather
than overwritten or reopened.

If the run says it does not know whether cycle history was applied, inspect
the destination cycles with the administrator before starting anything else.
Do not repeat the operation blindly. A preview or a finished run with failed
items is not proof of a completed migration.

## Preview before applying

Select **Preview transfer**. Check the source project, capture interval,
document digest, and the **Created**, **Updated**, **Skipped** and **Failed**
counts. Expand the item outcomes to understand unsupported or refused items.
Resolve failed items before applying.

Changing the file or mode clears the preview. A preview describes the
destination at that moment; someone else's changes can affect the final
result. Review it, then select **Start import** or **Apply catch-up** for the
chosen mode. A project with an import already queued or running cannot start
another through this page.

An accepted request is not a finished import. Follow the run in **ReasonOS
import history** and inspect its counts and item outcomes. A run can finish
with skipped or failed items, or stop after importing some records.

## Recover safely

* **File or preview failure:** follow the notice. A read retry keeps the file
  and mode; it does not start an import.
* **Unknown start outcome:** refresh history and inspect the run before
  starting another. The page does not retry a start automatically and keeps
  it locked. An absent history entry alone is not proof that nothing started.
* **History or item outcomes unavailable:** use the read's **Try again** or
  **Refresh history** action. Do not infer that the import failed or that no
  records changed.
* **Sign-in required:** signing in takes you away from this page. Afterwards,
  choose the file and mode again, then make a new preview.
* **Catch-up unavailable on this deployment:** ask the workspace administrator
  about support. The page never substitutes an ordinary import for catch-up.

Use **Copy error details** when asking for help. It includes a stable operation
code, such as `project.work_transfer.file.invalid` or
`project.work_transfer.run.failed`, and the request reference when available.
An unavailable reference is reported as unavailable. These support details do
not include the transfer file, issue content or raw server errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.