Skip to content

Import data#

The import wizard walks you through file upload, content, field mapping, matching existing nodes, writable fields, rules, and preview. On the File step you can choose a file or drop it on the upload button, the worksheet/CSV/ReqIF list, or anywhere else on that step. You see what will be created, updated, or skipped before anything is saved.

Supported formats#

Format Typical file Multiple node types
CSV .csv or .zip Yes, one file per type in the ZIP
Excel .xlsx or .zip Yes, one worksheet per type
JSON .json or .zip Yes, several types in one file
ReqIF .reqif or .reqifz ReqIF types are mapped

New attachment files require the full export ZIP (with an attachments/ folder). A standalone CSV or Excel file only carries paths, not file bytes. In the wizard you can optionally import attachments: updates skip files that already exist on the matched node; new files need the package ZIP.

While you review the preview, attachment packages are held on the server for a short time (about 15 minutes). Closing the wizard without importing releases that staging; committed imports clear it immediately.

Node type: who needs type_slug?#

Every imported node needs a valid node type from your project. Where that type comes from depends on the format.

CSV and Excel#

You do not have to put the type in the file.

For one file or one sheet, pick the node type in the wizard (Content step). All rows use that type.

For several files or sheets, assign each file or sheet to a type in the Content step. The wizard choice is enough.

You only need a type_slug column on each row when different types share the same table.

JSON#

Every node in the JSON must have a type_slug field. Unlike CSV or Excel, the JSON import has no type picker in the wizard.

JSON assumes schema-aware data

JSON is the round-trip format for automation: re-importing OakCore exports, CI/CD pipelines, or custom tools that write OakCore field names directly. Property keys must match your node types — there is no column-mapping step like CSV or Excel.

Typical use cases:

  • Re-importing an OakCore export (same or different project)
  • Automated data exchange between systems
  • Integration with scripts that produce OakCore-compatible JSON

Field behavior in the wizard:

  • Known fields (title, notes, custom attributes on the type) import automatically
  • Unknown attributes: skip or create a new field (Fields step)
  • Structural errors (type_slug missing or unknown, invalid identifier, invalid value type) block the import

Hard constraints:

  • Every node object needs a type_slug that matches an enabled type in your project
  • Property keys must already be OakCore field names — there is no mapping step
  • Missing or unknown type_slug blocks the import; unknown extra attributes can be skipped or added in the Fields step
  • For spreadsheets with foreign column names, use CSV or Excel instead

Several types in one file work when each entry carries its own type_slug. If the field is missing or does not match a type in your project, the import is blocked.

ReqIF#

ReqIF files do not contain OakCore type_slug values. In the wizard you choose which requirement type in your project the imported objects become.

ReqIF attribute types (string, XHTML, enumeration, integer, real, boolean, date) are preserved on import where they match OakCore field types.

Other wizard options#

Matching: Decide whether imported rows update existing nodes or are always created as new. For an OakCore round trip, use its stable exchange_id. For new deliveries from DOORS, Excel, or another source, select a stable source-owned field such as ext_id. OakCore uses only the selected identifier and never silently falls back to another field.

Writable fields: When the import can update existing nodes, explicitly choose the fields each node type may change. The field list uses one header checkbox that selects or clears all fields for that type. For an RFQ, for example, you can allow only the supplier rating and comment while protecting requirement text and title. New nodes still receive all mapped, valid fields.

Relations (ReqIF only): Optionally import links from a ReqIF file when both ends resolve in the project.

Attachments: Optionally upload files from an OakCore export package to the matching nodes. Files that already exist with the same name, size, and type are skipped.

Containers: container_path controls placement in the project tree. Without it, new nodes go to the inbox.

Import history#

After a successful import, OakCore keeps an import run for the project: filename, who imported, when, and counts (created, updated, unchanged). Open Import → Import history to see which nodes were part of a run, filter by result, and open a node for field-level diffs in its History tab. Changes from an import are linked back to that run in node history.

Import history is kept for the same period as node edit history (Settings → Data retention → Node edit and import history retention).

Re-importing an OakCore export#

When you import from the same or another OakCore project, the wizard often recognizes that from metadata. JSON, CSV, and Excel exports usually include type_slug, exchange_id, and the exported revision. OakCore can therefore find the corresponding nodes and warn about parallel changes when a file returns to its origin project.

Back to overview: Import and export.