Overview
DASHBOARD GUIDE

Migration

Move from another Discord bot to SYNTHET safely. The dashboard scans your server, proposes candidates to migrate, plans the work, executes inside a maintenance window, and gives you a full audit trail and rollback path.

Path
DashboardSettingsMigration
Module
migration
Required permission
migration.view

Before you start

Migration is a destructive operation. Walk through every prerequisite before clicking New migration.

  • You have the migration.view capability on this server
  • A pre-execution snapshot exists in the Backups module
  • The Migration module is enabled in Modules
  • Source bots are still in the server so SYNTHET can read their messages
  • You have agreed an outage / maintenance window with your community

What you'll see

The Migration dashboard has a runs list at the top, a New migration button, and four tabs that appear once you select a run.

Candidates
Plan
Execution
Audit
Candidates
Items the scan thinks are migratable, with confidence and notes.
Plan
Concrete actions the bot will take, with cost estimates, awaiting approval.
Execution
Live progress, results table, and the rollback / execute controls.
Audit
Full event history for the run with actors, actions and timestamps.

Creating a new run

Click New migration in the page header to open the create form.

Mode

Snapshot only
Capture current state without observing source bot behaviour. Fastest, but loses anything that changes after the snapshot.
Snapshot + observe
Capture the snapshot, then watch the server for a configurable observation window so transient state (e.g. running giveaways) is captured. Recommended for most migrations.

Required fields

ChannelsMulti-select

Which text channels to scan. Use Select all to pick every text channel up to the per-run cap.

Observation durationNumber

Hours to observe (Snapshot + observe only). Bounded between the configured min and max — typically 1–48 hours.

Example: 24

Max channelsNumber

Optional override of the per-run channel cap.

Max messages per channelNumber

Optional override — limits how deep the scan reads in any single channel.

Max total messagesNumber

Optional global cap across the run.

Limits override

The collapsible Limits (optional) section lets you tighten the defaults for this run. Use it when migrating very large servers where the default cost would be too high.

Runs list

Above the tabs, a table lists every run on this server.

  • Each row shows the truncated Run ID, Mode, Status, channel count, who initiated it and the creation time.
  • Click any run to load it — the four tabs appear below and the run becomes the focus of the page.
  • Status chips use colour: blue for in-progress, amber for awaiting review, green for completed, red for failed.

Status banners

  • Executing — info banner with live progress.
  • Failed — red banner with a button to jump to Audit and find the failing event.
  • Rolled back via backup — neutral banner showing the timestamp of the rollback.
  • Observing — a card with a progress bar, the configured window length, and a Stop early button.

Candidates tab

The scan output. Every candidate is something the bot believes belongs to a source bot's data model.

Stat tiles

  • Total — every candidate the scan produced.
  • Confidence — average confidence score across all candidates (0–100).
  • Confirmed — candidates you have approved for migration.
  • Needs review — low-confidence candidates that require a human decision.

Type distribution chart

A bar chart that breaks the candidates down by type — for example economy balances, level data, sticky messages, suggestions or auto-purge configs. Useful for spotting one source-bot feature dominating the scan.

Filters

TypeDropdown

Filter to a single candidate type — economy, level, sticky, suggestion, etc.

StatusDropdown

Filter to PROPOSED, NEEDS_REVIEW, CONFIRMED or REJECTED.

Per-candidate card

  • Type chip, confidence percentage and current status.
  • Source channel, source author and the matched signature (e.g. a regex hit on a known bot's prefix).
  • Free-text Notes field where you can record why you confirmed or rejected.
  • Action buttons: Confirm, Reject and Mark as needs review.

Plan tab

Once you have triaged candidates, generate a plan. Each plan item is a concrete action SYNTHET will take during execution.

Generate plan

The first time you visit the Plan tab the page shows a single button labelled Generate plan. After clicking it the tab fills with stats, charts and a plan items table.

Plan stats

  • Actions — total plan items.
  • Messages created — how many new messages execution will post.
  • REST calls estimated — total Discord API calls the run will use.

Cost distribution

A chart that buckets plan items by REST cost so you can spot expensive items before approving.

Approval

  • Approval requires typing the exact phrase shown in the Confirm phrase hint into the input.
  • The Approve button only enables once the phrase matches — preventing accidental approvals.
  • After approval a green banner appears confirming the plan is ready to execute.

Plan items table

Lists every action with item id, originating candidate id, action type (e.g. create_message, set_role), status (pending / executed / failed / skipped / rolled back), REST cost and message count.

Execution tab

The danger zone. Every action here moves the server from its old state to its new state.

Execution stats

  • Total executed, Succeeded, Failed, Messages created, Messages deleted.
  • The Execution timeline chart shows results over time so a stalled execution is obvious.

Execute add-only

  • Only available when the plan is approved and a pre-execution backup snapshot exists.
  • If the backup is missing, a red banner appears explaining what to fix in Backups.
  • Type the execute phrase into the input — the button stays disabled until the phrase matches.
  • Click Execute add-only to begin. The run status becomes Executing and the banner appears at the top.

Results table

Each row corresponds to one phase of execution with its result, start and completion time. Useful for narrowing down where a partial failure occurred.
Add-only is intentional
The Execution tab only adds new content. Deletion of legacy data is intentionally a separate, manual cleanup step performed after you have verified the migration succeeded. This means a botched run leaves both old and new data side by side — never an empty server.

Audit tab

The complete event log for one run.

Audit stats

  • Events — total audit rows for this run.
  • Distinct actors — how many people / processes touched the run.
  • Distinct actions — number of unique action codes (e.g. plan.approve, execute.start).

Events table

Time, truncated actor id, action chip, channel list and a JSON-rendered Counts column showing message / role / channel counts touched. Click Load more to fetch older events.
Audit access
This tab requires the migration.view_audit capability — a strict superset of the migration.view permission needed to see the rest of the dashboard. Some staff can drive a migration while only senior admins see the audit trail.

Common tasks

Step-by-step recipes for the work most operators do most often.

1

Run a snapshot-only dry run

Use this first to see what the scan would find, without observing.

  • Open DashboardSettingsMigration.

  • Click New migration, set Mode to Snapshot only.
  • Pick three or four representative channels to scan.
  • Click Create run. The run appears in the table with status Scanning then Ready for review.
  • Open the Candidates tab to triage. No data is changed yet.
2

Plan and approve

Once candidates are triaged, generate the plan and approve it.

  • Open the Plan tab and click Generate plan.
  • Review the action count, message count, REST estimate and the cost distribution chart.
  • Type the approval phrase shown beside the input, then click Approve.
  • The green banner confirms the plan is ready. The Execution tab now activates.
3

Execute during your maintenance window

Final step. Make sure your community is informed before clicking the button.

  • Confirm a pre-execution backup exists in Backups. The Execution tab will tell you if it does not.
  • Type the execute phrase into the input and click Execute add-only.
  • Watch the timeline chart and the executions table for failures.
  • If something goes wrong, open the Audit tab to identify the failing action, fix it, then re-run only the affected items.
  • If the run cannot be salvaged, restore from the pre-execution backup snapshot.

Troubleshooting

The Execute button stays disabled
The button only enables when (a) the plan is approved, (b) a pre-execution backup exists, and (c) the execute phrase in the input matches exactly. Check all three.
The plan keeps failing to generate
Plan generation requires that observation has completed (for Snapshot + observe) or that the snapshot finished (for Snapshot only). If the run is still Observing, click Stop early on the observation card or wait for the window to close.
Candidates are flagged 'Needs review'
The scan was not confident enough to auto-confirm them. Read the Detection reason on each candidate card and either confirm, reject, or leave them excluded. Excluded candidates do not appear in the plan.
Execution failed partway through
Open the Audit tab to find the failing action. Because Execute is add-only, no data has been deleted — the worst case is duplicated content. Inspect the failed plan items, fix the underlying issue (e.g. missing channel permission), then start a new run for the failed items only or restore from the backup snapshot if you prefer.
Messaging
MLI