Using the multi-collection importer¶

For bulk imports that span multiple collections, use kcworks-multi-collection-importer (kcworks_import_client.multi_collection_importer). Install with the yaml extra if you use YAML manifests (pip install -e ".[yaml]"). It reads a JSON or YAML manifest, creates any missing collections via the communities API, optionally links parent/child collections, and then calls the same import logic as the single-collection importer for each entry.

The single-collection importer remains usable on its own. The multi-collection wrapper is for when you want one command driven by a manifest.

Manifest format¶

YAML example:

collections:
  - slug: my-university
    name: My University
    metadata: ./university/metadata.json
    files: ./university/files.zip
    output: ./university/response.json

  - slug: dept-history
    name: Department of History
    parent_slug: my-university
    metadata: ./history/metadata.json
    files:
      - ./history/a.pdf
      - ./history/b.pdf
    id_scheme: neh-recid
    notify_record_owners: true

Equivalent JSON:

{
  "collections": [
    {
      "slug": "my-university",
      "name": "My University",
      "metadata": "./university/metadata.json",
      "files": "./university/files.zip",
      "output": "./university/response.json"
    },
    {
      "slug": "dept-history",
      "name": "Department of History",
      "parent_slug": "my-university",
      "metadata": "./history/metadata.json",
      "files": ["./history/a.pdf", "./history/b.pdf"],
      "id_scheme": "neh-recid",
      "notify_record_owners": true
    }
  ]
}

Relative paths in the manifest are resolved against the manifest file’s directory. YAML manifests require PyYAML.

Each collection slug may appear only once in a given manifest. The importer treats that as a single create/link/import batch for that collection. Duplicate slugs are not supported as multiple batches (later rows silently override earlier ones for the same slug). To import more records into a collection later, use another manifest run or the single-collection importer.

Optional per-entry fields:

id_scheme / alternate_id_scheme — override the CLI defaults for that collection. Schemes must already be defined in KCWorks (RDM_RECORDS_IDENTIFIERS_SCHEMES), or arranged with the KCWorks team for addition before import.
notify_record_owners — true/false for that collection; overrides --notify-record-owners for the entry.
no_updates — true/false for that collection; overrides --no-updates for the entry. Default is to allow metadata updates on existing matches (with file reconciliation as in Files when re-importing an existing work (no_updates is "false")).

Parent / child links¶

With --assign-parents, entries that list parent_slug are linked under that parent. The script:

Ensures the parent has children.allow=true (collection owners can set this on KCWorks).
Submits a subcommunity join-request. When the OAuth user owns both collections, the request is auto-accepted and the link is created immediately.

See Collection hierarchy and subcollection requests for the full operator documentation on collection hierarchy.

Command-Line Arguments¶

Argument	Description
`--api-key KEY`	API key (or `KCWORKS_IMPORT_API_KEY`, or interactive prompt).
`--manifest PATH`	Path to the JSON/YAML manifest (or `KCWORKS_IMPORT_MANIFEST_PATH`, or interactive prompt).
`--assign-parents`	Create parent/child links for entries that list `parent_slug`.
`--output PATH`	Folder for per-collection timestamped result JSON reports. Defaults to the manifest file’s directory. Ignored with `--suppress-reports`.
`--testing`	Use a local testing instance (`https://localhost`).
`--notify-record-owners`	Default notify flag for entries that do not set `notify_record_owners`.
`--id-scheme SCHEME`	Default import dedupe scheme (default: `import-recid`); overridable per entry.
`--alternate-id-scheme`	Default secondary dedupe scheme; overridable per entry.
`--no-updates`	Default block on metadata updates for existing matches; overridable per entry. Default: allow updates (see Files when re-importing an existing work (no_updates is "false") for files).

Usage Example¶

kcworks-multi-collection-importer \
  --api-key "your-api-key" \
  --manifest "import_manifest.yaml" \
  --assign-parents