# Migrate from Contentful

> Import a Contentful space into Galerne from a contentful-cli export, and export Galerne content for contentful space import: options, mapping and what each direction loses.

The Contentful source reads the JSON file that `contentful space export` writes. It does not call the Contentful API: export first, then import the file.

## Import

```bash
contentful space export --space-id abc123 --download-assets --export-dir ./ctf
galerne import --from contentful --file ./ctf/contentful-export-abc123-master.json --dry-run
galerne import --from contentful --file ./ctf/contentful-export-abc123-master.json
```

Options go after `--from` as flags in kebab case (`projectId` is `--project-id`). With the `import_from` tool, they go in `options`. See the [migration overview](/docs/migrate.md) for the shared flags, the report and re-runs.

| Option | What it is |
|---|---|
| `file` | The export JSON file |
| `url` | The same file at a public URL (tools) |
| `data` | The same JSON inline (tools) |
| `locale` | The default language. Default: the export's default locale |
| `assetsDirectory` | Where downloaded assets are, relative to the file. Default `assets`, then the file's folder. Without files, assets are downloaded from their URLs |

## How content maps

| Contentful | Galerne |
|---|---|
| Content type | Document type; its display field becomes the preview title |
| Entry id | Document id, kept |
| Symbol, Text | `string` (options from an `in` validation), `text` |
| Symbol named `slug` | `slug` when every value is valid and unique per locale, else `string` |
| Rich Text | Rich text |
| Integer, Number, Boolean | `number` (`integer` for Integer), `boolean` |
| Date | `date` when every value is a plain date, else `datetime` |
| Location | `geopoint` |
| Object (JSON) | `code` with language `json` |
| Link to entry, array of links to entries | `reference`, list of references |
| Link to asset, array of asset links | `image` or `file`, blocks of images or files |
| Array of Symbol | List of strings |
| Localized fields | Localized fields |
| Published and changed entries | Published version, and a draft when the entry has unpublished changes |

## Rich Text

Hyperlinks become links, entry hyperlinks become `doc:<id>` links and asset hyperlinks `media:<id>` links. Embedded assets become images. Embedded entries, in blocks or inline, become embeds of an `embeddedEntry` block that holds a reference to the entry; an inline entry is placed after its paragraph, with a warning. Embedded resources become embeds of an `embeddedResource` block that keeps the URN.

## What the import loses

The report lists each of these when it happens.

- The export holds only the latest version of an entry. An entry with changes after its last publish is imported with those changes as published, with a warning.
- Translations are field-level only.
- Archived entries and assets are skipped, and so are entries whose content type is missing from the export.
- Field types not listed above are left out, with a warning. Unknown rich text marks are dropped and reported.

## Export to Contentful

```bash
galerne export --to contentful --out ./ctf-export --space-id galerne
```

| Option | What it is |
|---|---|
| `spaceId` | Space id written in asset URLs, default `galerne` |

The folder holds `contentful-export.json` with content types, entries, assets and locales, the asset files under `assets/`, and a `README.md`. Load it with `contentful space import --content-file contentful-export.json --upload-assets --assets-directory assets`.

The export loses:

- One version per document: the draft is written, and the published version is left out with a warning.
- Image alt text, hotspot and crop are not written: the field becomes a plain asset link.
- Blocks other than images and files become separate linked entries.
- Tables, objects and lists other than strings or references become JSON `Object` fields; URL, email and color fields become Symbols.
- Code blocks become paragraphs with a code mark.
- Embeds go back as embedded entries. An `embeddedEntry` links to its entry again; other blocks become entries of their own content type, and the rich text field allows those types.
- Document-level translations get extra `language` and `translationOf` fields.
- Ids that Contentful does not accept are rewritten with a hash.
