ColdFront Exporter v1

This project is a ColdFront v1.1.x plugin specifically designed to aid in migrating to ColdFront version 2.x and above. ColdFront v2.0.x is a complete re-write and the data models are not backward compatible. The recommended mirgration path is to export the ColdFront v1.1.x database into YML files that can be imported into ColdFront v2 using the coldfront-initializer plugin.

What this tool does

The exporter reads a ColdFront v1 database and. writes one YAML file for each record type. The YAML files can then be ingested by the coldfront-initializer plugin and loaded into ColdFront v2.

The exporter is configuration-driven. For simple use cases writing Python code is not required, instead you write a configuration file in TOML format with site specific customizations. If your site has heavily customized ColdFront v1.1.x, more advanced ways of customizing the exporter are also supported.

Install

Install the package with pip.

$ uv pip install coldfront-exporter-v1

Add the app to INSTALLED_APPS in your local_settings.py file.

INSTALLED_APPS += ["coldfront_exporter_v1"]

Quick start

Create a configuration file named coldfront-exporter-config.toml. The simplest configuration exports all data with no filters.

[export]

Run the export command.

$ COLDFRONT_CONFIG=local_settings.py uv run coldfront export_database --output /path/to/yaml/

The command writes one file per record type. The command does not overwrite an existing file. To change the config file location, use the --config flag or the COLDFRONT_EXPORTER_CONFIG environment variable.

Now import the YAML files with coldfront-initializer.

The configuration file

A configuration file has several optional sections. A missing section means "export everything".

The main sections are:

• [export] — global settings, such as which exporters run.
• [models.<Name>] — filters on the v1 database models.
• [exporters.<Name>] — per-exporter settings, such as attribute mapping.
• [mappings] — statuses, slugs, and resource references.
• [hooks.<Name>] — Python functions at each pipeline stage.

Here is a richer example.

[models.Project]
include = [{ field = "status__name", value = "Active" }]

[models.Allocation]
include = [
  { field = "status__name", value = "Active" },
  { field = "project__status__name", value = "Active" },
]

[mappings.statuses.Allocation]
active = "active"
default = "renew"

The file coldfront-exporter-config.toml.example is a complete example. It documents every section and every option.

Customize

There are four layers of customization. Use the simplest layer first.

Layer 1 — Configuration

Most changes are configuration only. You can set filters, attribute mapping, status mapping, slug rules, resource mapping, roles, and exporter selection.

For example, exclude a user.

[models.User]
exclude = [{ field = "username", value = "admin" }]

Layer 2 — Hooks

A hook is a Python function in your own module. You register the function path in the configuration. Hooks run at named stages of the export.

Hooks are keyed by exporter name, not by model name. A hook on slurm_accounts does not affect allocations.

For example, add a tag to each project.

[hooks.projects]
post_serialize = ["my_site.hooks.project_add_tags"]

The hook function has this signature.

def project_add_tags(record, instance):
    record["tags"] = ["example"]
    return record

Layer 3 — Exporter class

An exporter class inherits a shared driver. Most exporters only declare attributes. For structural changes, override a lifecycle method.

For example, the resources exporter overrides the query and the iteration to walk the resource tree.

Layer 4 — Custom exporter

If no shared behavior fits, for complete control you can register your own exporter class. The class does not share the driver.

How the layers work together

Each exporter produces one YAML file. The shared driver runs the filters, the hooks, and the serializer. The driver then collects and renders the records.

The base exporter has these attributes that state the export data:

• name — the registry key and the hook key.
• model — the v1 model to read.
• serializer — the field-mapping serializer.
• key_field — dict output key (users and groups).
• skip — drop a record when the condition is true.
• dedup — remove duplicate records with the same key.

Most sites only change Layer 1 and Layer 2.

License

coldfront-exporter-v1 is released under the Apache 2.0 license. See REUSE.toml.