Data Migration

Promotes schema changes from a development FileMaker file into a production file using the FMDataMigration tool, run via AWX. The target file’s live data is preserved — only the schema structure is updated.

AWX template: Generic - FMS Data Transfer - Migration
Primary use: Promote dev to prod.

All pages in this flow show an Experimental warning banner.

The wizard has four steps:

Select a client
Select the clone (schema) file
Select the live data file
Review and confirm

The two servers involved are named for what they contribute — this matches the FMDataMigration vocabulary:

The clone host provides the clone (schema) file. It is not where your live data lives. You select a normal hosted file; the job clones it for you.
The data host holds the live data file that will be migrated into the clone — and it receives the migrated result.

1. Select a client

Choose the client group this migration belongs to. Only groups with migration-eligible servers (those with a configured deploy chain) are shown.

2. Select the clone (schema) file

The clone host provides the clone (schema) file — the template whose structure will be applied to the live data. Your live data file is not selected on this step; that happens in step 3.

This is typically your development or staging server.

Do not create or upload a clone yourself. Select the normal hosted file — the AWX job creates the clone from it as part of the migration. No clone file will appear in the list, and none is needed.

An info banner is shown on this step as a reminder of the clone host’s role, alongside a warning banner telling users not to pre-clone the file themselves.

Select the clone server, then click Load databases to list its hosted .fmp12 files via the FileMaker Admin API. All files known to FMS are shown regardless of open/closed status. Select the file whose schema you want to promote.

3. Select the live data file

The data host holds the live data file — the production file whose data will be preserved and merged into the schema.

The selected file on the data host will be overwritten after migration completes.

A warning banner is shown on this step. Select the data server (only servers in the clone server’s deploy chain are shown), then click Load databases. Select the file whose data you want to preserve.

4. Review and confirm

A summary card shows:

Clone host — server name and clone (schema) file
→ — direction of the migration
Data host — server name and live data file

Disk space

A stacked bar shows the data host’s databases volume: what is already used, the clone file being copied over, and — when Backup data file before migrating is enabled — the extra copy of the existing data file. The disk-capacity policy applies: above 90% projected usage the Run Migration button stays disabled until you tick the acknowledgement, and above 95% the migration is refused. Both file sizes and the disk itself are read over SSH at launch, so a review page left open while the disk filled up is re-judged rather than trusted. If the host is unreachable the projection can’t be made, and the policy asks you to acknowledge that rather than blocking the run.

Options

Backup data file before migrating (`fms_transfer_backup`)

When checked, the live data file is moved out of its database folder under a timestamped name before the migrated file takes its place — a pre-migration backup of the data host’s file exactly as it was before the migration ran. The path is shown in the UI, on the data host:

<FMS backup dir>/auto-fms-data-transfer-backups/filename_pre-fms-migration-YYYYMMDDTHHMMSS.fmp12

filename is the data file’s own name without its extension, and the timestamp is the job’s start time (20260804T115910).

<FMS backup dir> is the data host’s configured FileMaker Server backup directory, read from the Admin API — the same root the Host from Backup — On-Server browser starts from, so the file is reachable in the portal once the job finishes. See Hosting the pre-migration backup if you need to put it back.

These backups are pruned after 14 days. At the end of every migration or refresh run, the role deletes .fmp12 files older than fms_transfer_backup_retention_days (14) from that folder — so a backup that has aged out disappears the next time any migration or refresh runs against the host, not on a schedule of its own. The portal does not send that variable, so the role default applies. Copy the file elsewhere if you need to keep it longer.

Sync migrated file back to clone host (`fms_transfer_sync_back`)

When checked, the migrated output file is copied from the data host back to the clone host after migration completes, replacing the clone host’s own copy in its database folder.

The clone host’s copy is backed up first, the same way and to the same place as on the data host (fms_transfer_sync_back_backup, on by default and not exposed in the portal), so the clone host also keeps a pre-sync copy of its file:

<clone host FMS backup dir>/auto-fms-data-transfer-backups/filename_pre-fms-migration-YYYYMMDDTHHMMSS.fmp12

It carries the same timestamp as the data host’s backup and is pruned on the same 14-day retention. Host it back with the steps in Hosting the pre-migration backup, selecting the clone host instead.

Container directories to sync back (`fms_transfer_sync_back_dirs`)

Only shown when Sync back is enabled. If container directories exist on the data host, a checklist appears. Select any directories to sync back alongside the file. Unselected directories are not transferred. This variable is only submitted to AWX when at least one directory is selected.

Data-host options (during the migration)

These options apply to the data host for the duration of the migration only — the portal reverts them when the job finishes.

Option	Variable	Effect
Block new connections	`fms_block_new_connections`	Blocks new FileMaker user connections on the data host while the migration runs, then re-enables them when finished.
Disable schedules	`fms_disable_schedules`	Disables enabled script schedules on the data host (waiting for any running schedules to finish first), then re-enables the ones it disabled when finished.

Data migration flags (`fms_transfer_flags`)

Optional flags passed through to the FileMaker FMDataMigration tool. Check any that apply; the selected flags are space-joined and submitted as fms_transfer_flags. None are selected by default.

Flag	Label	Effect
`-ignore_valuelists`	Ignore value lists	Keep value lists from the clone instead of migrating them from the source data file.
`-ignore_accounts`	Ignore accounts	Keep accounts and privileges from the clone instead of migrating them from the source data file.
`-ignore_fonts`	Ignore fonts	Skip migrating font information from the source data file.
`-reevaluate`	Re-evaluate auto-enter calcs	Re-evaluate auto-enter and unstored calculations during migration.
`-rebuildindexes`	Rebuild indexes	Rebuild field indexes after migration instead of carrying them over.

1Password overrides (`op_dmt_creds` / `op_data_ear_key` / `op_schema_ear_key`)

By default the AWX job reads its secrets from the standard entries in the automation’s own vault — fms-dmt-creds_<host> for the DMT account and fms-ear-key_<host> for EAR keys. Creating an entry with one of those names in another vault does not get picked up. Three optional fields point any of those lookups at a specific entry of your choosing for this migration:

Field	Redirects
DMT credentials entry	The FileMaker account the migration tool signs in with on the data host. The entry must provide `username` and `password` fields.
Data file EAR key entry	The EAR key for the live data file on the data host.
Clone file EAR key entry	The EAR key for the clone file on the clone host.

Each field requires a full op://<vault>/<item>[/<field>] secret reference — the vault must always be named, it is never assumed. DMT credential references must be entry-level (op://<vault>/<item>); EAR key references may name the field holding the key (defaults to password). Leave blank to use the standard entry. Secrets are always pulled from 1Password at run time — the portal never stores them, only which entry to look up. The values are submitted on the fms_transfer_files entry and resolve per-file → per-server (host_vars) → standard entry, matching the fms_data_transfer role.

To use an entry outside the central automation vault, you must grant the 1Password automation user access to the vault holding it — the wizard’s help text names the user (systems-shared by default; deployments configure it via the OP_AUTOMATION_USER env var). The automation cannot read entries it has not been given access to — without the grant, the job fails at run time when it tries to resolve the reference.

A Verify access button under the fields resolves each entered reference and reports per field whether the automation can read it — an entry that is missing, empty, or in an unshared vault shows as not accessible. Use it before launching. The same check runs automatically when you save a template with overrides (an inaccessible entry blocks the save) and on the template’s Verify page.

Script schedules (`fms_transfer_pre_migration_script_schedule` / `fms_transfer_post_migration_script_schedule`)

The portal reads the script schedules configured on the data host from the FileMaker Admin API (GET /schedules) and offers two dropdowns:

Pre-migration schedule — runs on the data host before any file is closed, while files are still hosted.
Post-migration schedule — runs on the data host after every file has been migrated and reopened. When Sync back is enabled, the schedule runs before the migrated file is copied back to the clone host — so any changes it makes are included in the synced-back copy.

Each dropdown defaults to — None — (no schedule runs). Selecting a schedule submits its name to AWX; the fms_data_transfer role resolves that name to its schedule ID on the data host and runs it via fmsadmin, so it runs even when Disable schedules is on. Disabled schedules are labelled as such in the dropdown but can still be selected. The chosen name is re-validated against the data host’s live schedule list at launch, so a selection that no longer exists is rejected with a clear message instead of failing inside the job. The variable is omitted from the AWX submission when — None — is selected.

If no schedules are configured on the data host, or the Admin API cannot be reached, the card shows an explanatory note instead of the dropdowns.

Save as template

The Save as template card saves everything on this step — servers, files, and all options above — as a reusable template under a name of your choice. Saved templates live in the Templates section (linked from the wizard’s start page), are shared with everyone who has access to both servers, and can be verified and run from there without re-walking the wizard. Saving again with a name you already used updates your existing template.

Production confirmation

If the data host is a production server, the Run Migration button is red and a confirmation modal appears when clicked. Read the prompt carefully before confirming.

Admin debug panel

Staff users see a collapsible AWX extra vars panel showing the exact variables that will be submitted to AWX. The panel updates dynamically as options change — useful for verifying the job configuration before launch.

Job output

After launch, the portal redirects to the job output page, which polls AWX every 4 seconds and displays:

Status — Pending, Running, Succeeded, Failed, Canceled
Duration — elapsed time
Output — stdout from the Wait for FMDataMigration to complete for AWX task. Output longer than 100 lines scrolls within a fixed-height container. No output is shown for canceled jobs.

A link to the job in AWX is shown in the card header. A Cancel button is available while the job is running.

Below the job card, an Options submitted to AWX summary lists the run’s parameters — hosts, files, backup/sync-back/connection options, script schedules, flags, and any 1Password overrides. It is read back from the AWX job’s own extra_vars, so it always reflects what was actually submitted (and reappears if you revisit the page later).

Hosting the pre-migration backup

If the migrated file turns out to be wrong, the pre-migration backup written by Backup data file before migrating can be hosted back onto the data host through Host from Backup — On-Server — it is an ordinary .fmp12 file sitting in the data host’s backup directory, so no separate restore flow is involved. Wait for the migration job to finish first; the file is only complete once the job has moved past replacing the data file.

Open Host from Backup — On-Server and select the client, then the data host — the server that was migrated, which is where the backup was written.
Browse to auto-fms-data-transfer-backups/ — a folder at the top level of the host’s backup directory, alongside the FMS backup folders — and find filename_pre-fms-migration-YYYYMMDDTHHMMSS.fmp12. If several migrations have run, the timestamp in the name identifies which one — pick the run you want to go back to. If the folder or the file is not there, the run either had Backup data file before migrating unchecked or the backup has been pruned.
Click Host, and keep the destination as the same server.
Edit the destination filename back to the original file name. It defaults to the backup’s own name, which still carries the _pre-fms-migration-… suffix — hosting it unchanged leaves you with a second, differently-named file alongside the migrated one rather than replacing it.
Because a file of that name already exists, the transfer overwrites it. Leave Backup existing file checked to keep a copy of the migrated file first, in case you want it back; it is written to <FMS backup dir>/hosted-db-backups/<filename without .fmp12>/<timestamp>/<filename>.
Tick Open database after transfer (with the EAR key, if the file is encrypted) to have FMS reopen the file straight away.

On a host with more than one database folder, a Database folders card appears on the review step. Because the original name is already hosted, the folder is fixed to the one holding that copy — the file goes back exactly where it was, and there is no choice to make. FileMaker resolves a hosted file by name, so the same name cannot be hosted from two folders at once.

This restores the data host’s file to its pre-migration state — the schema changes the migration promoted are gone with it, along with anything users have entered since the migration finished. If Sync back was enabled, the copy sent to the clone host is not affected and is still the migrated version.

AWX variables submitted

Variable	Value
`fms_transfer_mode`	`migration`
`fms_transfer_source_host`	Clone host hostname
`fms_transfer_target_host`	Data host hostname
`fms_transfer_files`	`[{"schema_file": "...", "data_file": "...", ...}]` — plus `op_dmt_creds` / `op_data_ear_key` / `op_schema_ear_key` when 1Password overrides are set
`fms_transfer_backup`	`true` / `false`
`fms_transfer_sync_back`	`true` / `false`
`fms_transfer_sync_back_dirs`	List of selected container directory paths (omitted if none selected)
`fms_block_new_connections`	`true` / `false`
`fms_disable_schedules`	`true` / `false`
`fms_transfer_flags`	Space-joined selected `FMDataMigration` flags (omitted if none selected)
`fms_transfer_pre_migration_script_schedule`	Name of the chosen pre-migration script schedule (omitted if none selected)
`fms_transfer_post_migration_script_schedule`	Name of the chosen post-migration script schedule (omitted if none selected)

The AWX variable names describe the direction of the transfer: source is the clone host and target is the data host. Note this is the opposite of FMDataMigration’s own CLI, where -src_path is the data file — the portal’s UI uses “clone host” / “data host” precisely to avoid that collision.

History

Completed migrations appear under the Migrations tab of the History page. Each record shows the clone and data hosts, files involved, the user, and the result (OK / Failed / Canceled). Running jobs are pinned at the top of the page with a View output button linking to the live job output. Finished jobs show a Result badge and a View output button. Failed jobs show the error in a tooltip on the badge.