# CMS import connectors

Source: https://docs.externa.qiick.io/docs/cms-import

Guided migration from an external CMS into Externa collections using the existing AI remote JSON import path — not a second sync engine.

> **Related**
> Pipeline details: [AI imports & sync](/docs/ai-imports-and-sync). Host allowlist: [AI configuration](/docs/ai-configuration) / [Environment variables](/docs/environment-variables). Webhook alternative: [AI API](/docs/ai-api).

## Profiles

`ImportRemoteJson` accepts optional `profile`:

| Profile     | Reshape before flatten                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `directus`  | Drop Directus system fields (`user_created`, `date_*`, …); promote first translation scalars (`title`, `body`, …) onto the row |
| `wordpress` | Unwrap `{ rendered: "…" }` envelopes on first-level keys (`title`, `content`, `excerpt`)                                       |

Without `profile`, behavior is unchanged: extract list → flatten (nested → JSON string).

## Recipe (Directus)

1. Allowlist the CMS host in `AI_REMOTE_IMPORT_HOSTS`.
2. Dry-run:

```text
ImportRemoteJson
  url=https://cms.example/items/pages
  profile=directus
  dry_run=true
  upsert_key=slug
  auth_bearer=…
```

3. Confirm proposed fields / preview rows (zero writes).
4. Re-run with `dry_run=false` (or omit). Large payloads queue via `ImportCollectionJob`.

AI chat presets: **Import from Directus URL** / **Import from WordPress REST**.

## Recipe (WordPress REST)

Same flow with `profile=wordpress` and a `/wp-json/wp/v2/posts` (or custom post type) URL. Application Passwords: pass `auth_header` as `Basic …` when Bearer is not used.

## Limits & gaps

| Topic      | Detail                                                                                    |
| ---------- | ----------------------------------------------------------------------------------------- |
| Row caps   | Sync/async thresholds (~200 queue, max 500 per call) — chunk URLs or repeat               |
| Media      | Featured images / file UUIDs are **not** auto-downloaded into Externa `File` rows in v1   |
| Relations  | Stored as JSON strings unless you reshape upstream                                        |
| Locales    | Directus `translations[]` → first locale scalars only; full locale matrix is out of scope |
| Write-back | One-way import only                                                                       |

Prefer [outbound webhooks](/docs/webhooks) + CI when the goal is rebuild/purge, not content migration.