Skip to main content

Copying an Archive

What is it for?​

The copy functionality duplicates the content of a source archive into a target archive.

Possible use cases:

  • publishing a filtered version of an archive: from a restricted internal archive, copy only the records that may be shared publicly (typically the ones without access restrictions) into a second archive that is exposed to a wider audience,
  • creating a new archive that starts from an existing archive's structure and content,
  • keeping a snapshot of an archive for review, training or reporting.

The copy is repeatable: running it again on the same source/target pair only applies the differences (created, updated, deleted, unchanged) — including records that fall out of the filter — so the target stays aligned with the source over time.

The endpoint requires the global role @archive:copyArchive (see Role Configuration).

Options​

The copy behaviour is controlled by the following query parameters:

  • sourceArchiveId — the archive to read from.
  • targetArchiveId — the archive to write to. Must be different from the source. If it does not exist yet it is created automatically.
  • forceOverride (default false) — allow overwriting an existing archive that was not itself created by a previous copy run. Without this flag, copying into such an archive is refused to avoid accidentally destroying content.
  • forceUpdateAllRecords (default false) — re-apply updates to every record on the target, even if it appears unchanged. Useful after configuration changes that affect derived data.
  • cloneAttachments (default false) — clone attachment files as well, see Attachment handling.

A source archive should always be copied into the same target archive on subsequent runs. Copying several different sources into the same target is not supported: because the copy synchronises the target with its source, records from a previous source would be treated as "missing" and deleted.

What is copied?​

A copy run transfers, from source to target:

  • Configuration: concept schemes, enumerations, rules, box configurations and forms.
  • Authority data: agents, accessions, concepts, locations and places.
  • Records: the record tree, subject to the filter (see below).
  • Attachments: optionally, the physical attachment files as well.

The relations between the copied items are preserved so that, for example, a record on the target still points to the same (copied) agent or location.

Filters​

The request body may contain filters that restrict which records are copied. Configuration and authority data are always copied in full so that filtered-in records keep their context (forms, vocabularies, authorities).

Supported filter types:

  • Access restriction — includes records with a given access-restriction status. This is the main filter for the "public archive" use case: keep only records that are not restricted.
  • Property value — includes records whose value at a given property path matches a regular expression.
  • AND / OR clauses — combine other filters with logical AND / OR.

A record is copied only if it passes every filter (top-level filters combine with implicit AND). Records excluded by a filter are pruned together with all their descendants, even if a descendant would individually pass — a record's context in the tree is preserved rather than promoting orphans.

Example: publishing a public archive​

Copy from myArchive into myArchive-public, taking only records that have no access restriction:

PUT /archive/copy?sourceArchiveId=myArchive&targetArchiveId=myArchive-public
{
  "filters": [
    { "type": "accessRestriction" }
  ]
}

Running the same request periodically keeps myArchive-public in sync with the current public subset of myArchive.

Attachment handling​

Attachments are binary files stored in an S3 bucket. The copy offers two modes:

Reference mode (cloneAttachments = false, default)​

The target archive shares the source archive's attachment bucket. No files are physically copied — the target simply references the same objects. This is fast and uses no additional storage, but the target cannot be given its own bucket configuration and depends on the source's bucket remaining available.

Clone mode (cloneAttachments = true)​

The physical attachment files are copied so that the target archive owns its own copies. In this mode the target archive may either share the source's bucket (files are copied within the same bucket under a different key) or be provisioned beforehand with its own bucket via PUT /archive so that files are copied cross-bucket. Clone mode is the right choice when the target must be independent of the source's storage — for the public-archive use case for instance, when the public archive lives in a separate, more accessible bucket.

Switching modes between runs is supported: when a previously clone-mode target is copied again in reference mode, the previously cloned files are cleaned up so no orphans remain.

A target archive produced by a copy run may itself be used as the source of a further copy run; the underlying storage is resolved through the whole chain, so no bucket needs to be reconfigured on intermediate archives.

Response​

The response is a summary of the run: source archive id, target archive, whether attachments were cloned, and per-category change counts (created, updated, deleted, unchanged; records also report rewired). This makes it easy to see at a glance what changed on the target.

The individual copy steps are additionally written to the application log with the same counts, so a copy run can be traced end-to-end.