Skip to content
Vellum

Back up and restore

This guide shows you how to keep a copy of the model of one project, and how to put that copy back. You need the viewer role to export and the editor role to import.

Vellum has two kinds of copy. Select the one that fits your goal.

Goal Use
Keep the model of one project in a file, or in your own repository The model document of this guide
Recover a complete instance after a failure: every project, scenario, promise, setting, account and credential Back up and restore in the runbooks. The operator of the instance does it.

The model document is not a backup of a project. It holds the elements, the relationships, the messages, the schemas and the contracts, with their truth labels. It does not hold scenarios, promises, evidence, views, decisions, cost sheets or project documents. Model document format lists what it holds.

The app has no button for the model document. Use the HTTP API. Use the HTTP API shows how to sign in and get the cookie file vellum.cookies.

Export the model

Section titled “Export the model”

  1. Find the ID of the project. It is the last part of the address of the project in the app: /projects/<project-id>.

  2. Export the model as JSON.

    Terminal window
    curl -sS --fail-with-body -b vellum.cookies -o model.json "$VELLUM_URL/api/projects/<project-id>/export"

  3. To get YAML, add ?format=yaml.

    Terminal window
    curl -sS --fail-with-body -b vellum.cookies -o model.yaml "$VELLUM_URL/api/projects/<project-id>/export?format=yaml"

The export orders each list by ID. The same model always gives the same file, so the file works well under version control.

The export reads the main model. It does not read a draft or a variant.

Keep the scenarios

Section titled “Keep the scenarios”

The model document has no scenarios. To keep them, save each scenario document.

Terminal window
curl -sS --fail-with-body -b vellum.cookies "$VELLUM_URL/api/projects/<project-id>/scenarios" | jq -r '.items[].id' |
  while read -r id; do
    curl -sS --fail-with-body -b vellum.cookies -o "scenario-$id.json" "$VELLUM_URL/api/projects/<project-id>/scenarios/$id"
  done

Put the model back

Section titled “Put the model back”

Import the file into the project that it came from.

Terminal window
curl -sS --fail-with-body -b vellum.cookies -H 'content-type: application/json' -d @model.json "$VELLUM_URL/api/projects/<project-id>/import"

For a YAML file, send the content type application/yaml and use --data-binary in place of -d.

The answer is 200 with the import result: the number of entries that the import added, changed and left unchanged, and one item for each entry. The import is one transaction: on an error, Vellum writes nothing and the answer names each refused entry. To see what an import does before it writes, add ?dryRun=true, or use the preview in the app: see Model document format.

Know what an import does before you use it:

  • It adds and it changes. It removes nothing. A fact that is in the model and not in the file stays in the model. Remove it by hand.
  • It writes to the main model directly. It makes no proposal and asks for no review.
  • It keeps IDs. A fact with an ID that exists in the project is changed. A fact with a new ID is added.

Limits

Section titled “Limits”
  • Another project of the same instance. A schema ID belongs to one project of an instance. In a second project of the same instance, the import gives each such schema a new ID and writes each reference to it with the new ID. The other facts keep their IDs.
  • Another instance. The import works when the instance holds none of the IDs of the file. The repository directory examples/orders holds a model document that you can import in this way.
  • Size. A file has 16 MB at most.

See also

Section titled “See also”