Tutorial
Your first migration
This walks through a whole migration of an Insites v5 instance to a new Insites v6 instance. An Insites v4 instance goes the same way. Allow an hour for a first run on an instance of about 10,000 records. You can close the page at any point: the migration carries on, and you come back to it from Migrations.
- A v6 instance to migrate to. Use a new, empty one for a first run. How to create one.
- A key for each instance. How to get them. For the new v6 instance, an access token from its CLI tab in Insites Console, which needs the Developer role. For a v5 source, its GraphQL admin key, or your Insites v5 Console email and password.
console.insites.iois the v6 Console now, so its sign-in is not the one a v5 source asks for. - If most of the site sits behind a sign-in, a test account for each kind of person, for example a member and a staff member.
How the wizard works
A migration has seven stages: Source, Destination, Transform, Plan, Load, Verify and Launch. Each stage is split into a few short steps. The footer at the bottom of the screen always holds Back, where you are ("Stage 4 of 7" and "Step 1 of 5"), and the one thing to do next, named for where it goes, such as Next: Before cutover. When the next thing cannot be done yet, the footer says why. The list down the side shows every stage, and you can open any step you have already reached. The address in your browser names the page, so a link or a reload opens exactly there.
The menu on the left can narrow to a row of icons on any page: press the arrow button at its bottom to collapse it or open it again. The tool remembers your choice in this browser, on every page. Inside a migration it starts narrow, so the stages sit beside it, until you open it. With the menu narrow, point at an icon, or move to it with the Tab key, to see its name.
Under each step's heading, one sentence says what the step is for. Each page shows a few numbers and the decision it needs. Everything else sits in a section you can open, with its count in the title.
1. Source
Sign in and click New migration. The first screen asks Where are you coming from?: choose Insites v5 instance, or Insites v4 instance for a v4 one. If you pick the wrong one, the tool says so when you connect. Is it v4 or v5? A platform that is not listed? The last tile, Request a platform, tells us which one you use. For a Webflow, Siteglide or Squarespace site, see where a site can migrate from, Migrate a Siteglide site and Migrate a Squarespace site.
The next screen asks only for the instance's address. It is tidied for you, so intranet.example.com becomes https://intranet.example.com. Use the live (production) instance, not a UAT or staging copy: the final sync copies the changes made on it. Press Next. When you come back to this step later, it shows a picture of the old site's home page, as a signed-out visitor sees it today.
The key screen shows how to get the key for the Insites version you chose. A v4 instance has no /admin/api page, so its UUID is in the Insites v5 Console. Paste its GraphQL admin key, or leave the key empty and fill in your Insites v5 Console sign-in with the instance UUID, then press Connect and check. Use one way, not both: if you fill in both, the tool asks you to clear one. If something is wrong, the fields keep what you typed so you only fix the mistake.
Once connected, What it holds shows one tile for each of the eleven Insites modules (CRM, Pipelines, Data, CMS, Forms, Events, Ecommerce, Assets, Locator, Permissions and API) and for the instance's own settings: people, constants, email and SMS notifications, GraphQL queries and integrations. Each module's card starts with counts in everyday words: contacts, companies, activities and tasks for the CRM, opportunities and pipelines for Pipelines, and each database by name with its items for Data. People, under the instance itself, says how many are contacts and how many are administrators. The table names and row counts are under Technical detail on each card. Open a tile to see its parts and where each one goes. What each status means.
Pre-flight checks of the old site
As soon as the key is accepted, the tool runs quick checks of the old site and shows them on What it holds, before anything is planned. They only read, they take up to about 20 seconds, and they make at most five requests to the site. Each line is Pass, Warning or Must fix, with what was found and what to do:
- The site's pages answer the tool. The home page is asked for with the tool's own User-Agent and the header
X-Insites-Migration-Tool: 1. When a plain request is turned away, the tool's browser tries the same page, and the line says which one read it. - Who is refusing, when something is: the old Insites hosting itself, which is on the Insites side and needs nobody asked, or something in front of the site, such as the owner's firewall or bot protection (Cloudflare or Akamai, for example). For that, ask whoever runs it to allow requests carrying
X-Insites-Migration-Tool: 1. - The key works for each part the plan needs: data, code, files and people on an instance, or each permission a platform's key carries.
- The file host answers, for a file the home page uses.
- robots.txt and the sitemap are there.
- Custom domain or instance address: whether the address is the site's own domain, which moves at cutover, or the platform's address for it.
- Size and a rough time: pages, rows and files, and roughly how long the move takes. The plan counts everything exactly.
A Must fix line does not stop you planning. It is shown again at the top of the plan's summary and as a job on the To do list, so you sort it out before the load. Press Check the old site to run the checks again at any time, for example once the site's owner has allowed the tool: the result is kept on the migration, and a line that is fixed leaves the To do list.
Read it the way you would read a packing list. If something you expect is missing, stop here: it means the key cannot see it.
2. Destination
The first screen has a Log in to Insites Console button. It opens Console in a new tab: create a new, empty v6 instance there, come back and press Next. Then connect the v6 instance: give its own address, as Insites Console shows it, ending prod01-insites.io or staging-insites.io, and paste the access token Console shows on the instance's CLI tab. Do not give the site's public domain: until the cutover, it still opens the old site. The tool checks your role and that the token is for this instance, then shows what it already holds. Every Insites v6 instance has every Insites module, so this step lists which version of each the instance has, as each module reports it. Beside each one is its latest release. A module behind it reads, for example, "CRM is on v6.1.5, the latest is v6.1.6": update it before the cutover in Insites Console, on the instance's Modules tab. It does not stop the migration, and it goes on the To do list as one job before cutover. When every module is current, the step says so in one line. Check again reads the versions again once you have updated, and every plan, including the final sync's, reads them again too, so the job goes once the modules are current. The job lists each module with the version installed and the version needed, such as "CRM: installed v6.1.5, needed v6.1.6". You do not have to come back to tick it: Check again on Verify or Launch, and the daily watch, read the installed versions too, and when every listed module is at or above the needed version the tool marks the job done by the migration tool. A job you ticked yourself is left as you set it, and a read that fails settles nothing. If the tool cannot read the installed versions or the latest releases, it says so and calls nothing current. If the tool's owner has turned it on, the next step, GitHub (optional), lets you choose a repository for the moved code: Send the code to GitHub. Then pick:
- Dry run: reads both sides and reports exactly what a migration would do, row by row. Nothing is written anywhere.
- Migrate: builds the same plan, then waits for you to approve it.
Start with a dry run. It can become the real migration later without reading the source again. Read the source starts the run: a progress bar and the time left show while it reads. You can close the page while it works: the migration carries on, and we email you when it needs you.
3. Transform
The stage opens with Analyze, which reads the whole instance: every table, person, page and file reference. The step shows how far it has got, and Next opens once the read is done. Most migrations need no changes after that: the rules for a v5 to v6 migration are already filled in. The stage then has one step for each kind of thing the instance holds, and each one lists what it has, how many, and what happens to each: Pages and code (which of the site's pages, and the code they are built from, are copied), Site files (which of its images, stylesheets, scripts, fonts and documents are copied), Databases (where each table goes, and which stay behind with a reason), Forms (every form, recreated in Insites with its database and past submissions), CRM (contacts, companies and pipelines), Users (who can sign in, their passwords, and the administrators), Ecommerce, Events, Locator, Other (anything Insites has no place for) and Redirects. A kind the instance has none of still shows, and says so. Last is Advanced, with Renames and rewrites (properties renamed or dropped, values and code rewritten, lookups matched) and Single records and secrets (single rows fixed or left out, columns redacted). Your choices save by themselves as you make them, and the plan updates in the background. Every setting.
4. Plan
The plan is exactly what will run. Four pages:
- Summary and decisions: the numbers, and anything that would stop the load, each with a button to fix it, for example dropping a field the v6 module does not have. Each fix asks you why, and the reason goes in the report. When you have fixed something, the plan says which earlier decisions your changes settled, and how. More on resolving the plan.
- What the load carries: the code, the files, every constant (untick any the new site must not have), people's passwords, and test accounts so pages behind a sign-in are checked too. How.
- Fixes: opens with what it needs from you, or says there is nothing to do. Code v6 will not take as it is, with the fix the tool can make shown line by line; links to the old instance's URL or file storage, which stop working when it is deleted, with a one-click rewrite; and, under Module versions, any module the new instance runs at an older version than the old one.
- Changes and what is not copied: what the transform changes on the way, every table, and what is not copied.
When nothing is left to decide, Approve the plan. If you made every choice but have not pressed Apply, the button says to apply your choices on the Summary page first. On a dry run the same page says Run it for real.
5. Load
The Confirm page says what the load writes, roughly how long it takes, and that you can roll it back until you close the migration. Type the plan's code to confirm you read it, then Load. The load writes rows with their original ids and dates, people with their profiles, the customer's code, the files the destination is missing and the constants. A large instance loads in steps; if the instance stops answering, the run waits and carries on from where it stopped. While the page is open it shows each step as it happens, without reloading. You can close the page: the load runs on the tool's servers whether or not a page is open, and we email you when the load finishes, with what it wrote, and again when the checks finish, with the verdict. While the page is open in a tab, the tab's title shows how far it has got, such as "42% loaded", then "Done" or "Needs you". Press Also tell me in this browser under the progress, and allow notifications when the browser asks, to have the browser tell you too when it finishes or needs you while you are on another tab. The browser asks only when you press it, and everything else works the same if you do not. If the load fails, you and Insites are emailed, and the page says why in plain words. Fix the cause, then press Carry on from where it failed: the load skips what it already wrote.
When the load finishes, Nightly sync asks one question: keep the new site in step with the old one every night until cutover? Until then people keep changing the old site, and a nightly sync copies those changes each night, so the final sync at cutover takes minutes. Choose Sync every night or Do not sync; you can change it later under Before cutover. The first page of Plan, of Load and of Verify also shows the whole launch as a timeline, so you know what comes after: the cutover, and a 14-day watch of the new site.
6. Verify
The checks start as soon as the load finishes, and run by themselves. They usually take a few minutes, and half an hour or more on a large site, because every page is compared on both instances. You can close the page: we email you when they finish, with the verdict. Every check is first tried on something known to be wrong, to show it can fail. A migration is verified when every row is identical, every person and profile is there, every file opens and every source record is accounted for. The site is compared page by page, anonymously and as each test account, and photographed on both instances. A site with more than 200 pages has a sample of 200 photographed, spread across the whole site. A check that could not read what it needed says so and does not pass. The migration then reads Verified, or Verified, with problems when a check failed. Result shows the verdict and only the checks that failed, field by field; Every check has the rest. Under In your words, Result also puts each count from What it holds, such as 13 contacts, beside the same count read from the new instance now. It does not decide the verdict. The new instance can hold more, because anything it held before the load is counted too. Fewer means some did not arrive, or were left behind on the plan. The checks.
When something failed, Things that need you, the step after Result, lists it as a short set of problems, in plain words, each with one thing to do about all of it. Page photographs and the errors the new site logged are under Worth a look, and every verification in full is in the Verification log. Files the old instance cannot serve either are one problem: Accept all as missing leaves them behind with one reason. Rows, code and the site's own files that differ are copied again with one button each. A person whose account was already on the new instance before the migration, such as whoever set it up, has a created date the tool cannot change: press Accept as they are. Open any problem to look through it five at a time and act on one item at a time; Undo takes an acceptance back. Nothing is checked while you do this: when you are done, press Check again and every check runs once more.
Under the problems, Worth a look lists what does not decide the verdict. One of these is every kind of error the new instance wrote to its log since the load began, with how often and on which pages. Fix each on the new instance before you switch the domain.
7. Launch
Launch guides the launch, in the order it happens. It opens with a timeline of the whole launch and a marker that says where you are, then a step for each part:
- Launch timeline: what happens from here to a live site, and when, with how far each part has got, for example "6 of 7 done". A part is ticked only when nothing in it is left open, and where you are is the first part that still has something open. Its circle pulses, unless your system is set to reduce motion.
- Before cutover: the jobs the new site needs from its first visitor, worked out for this site, such as setting up integrations and reCAPTCHA, setting constants, and checking forms. Each names what it is about: the people, the integrations, the files and the translation keys. Tick them off as you go, or have AI write each one as a task to paste into your project tool. A tick stays ticked while the checks run, and a final sync starts with the ticks and cutover steps already done. The nightly sync choice from the end of Load is here too, and can be changed.
- Cutover: going live, in order: freeze the old site, the final sync, the domain, and a look at the site on its domain, with the jobs that move the domain. Copy first, then cut over.
- After cutover: the jobs that need the domain on the new site, such as telling people who need to reset a password, switching webhooks back on, and deleting the old instance.
- Watch: for 14 days after cutover, every page and the new instance's error log, every 6 hours, with a summary email a day.
- Report: two PDFs. Summary for your client is one or two pages for the site owner, with the Insites logo and no check codes: the old address and the new, what was copied, the result in one line, what was not copied and why, and what is left to do. The Technical report records what the source held and where it went, every check and what it was first tried on, what was left behind and why, and every decision made, by whom and when. Both are kept in the tool as well as downloaded, so they are still there after the source instance is deleted. The reports.
- Close: when the new site has run cleanly, press Close the migration. To confirm, type the old site's address, or its Insites name, which the dialog shows, and press Close the migration. The tool removes its copies of the keys on close. Until then a load can be rolled back from the same page. After it, the migration is a record: nothing on it can be checked, loaded or synced again.
- The job names each form or page that checks reCAPTCHA, with the page it is on and its file.
- Get the site key and secret key in the Google reCAPTCHA admin console: the key the old site uses, of the same version. Add the new instance's address, and the site's own domain if it has one, to the key's domains. Google refuses a form sent from a domain the key does not list.
- Ask Insites support ([email protected]) to set reCAPTCHA up on the new instance with that site key and secret key, and ask how to send the secret key safely. A version 6 instance takes reCAPTCHA keys from Insites: Insites Console has no screen for it yet, and the admin's Integrations, reCAPTCHA page keeps keys this check does not read. We measured this on a test instance on October 24, 2026.
- Or, with no keys at all, switch each one to the platform's hCaptcha, which the new instance provides with its own key: change the spam_protection tag to
spam_protection "hcaptcha". A form whose spam protection setting names reCAPTCHA must name hCaptcha too, or its submissions may be refused. - Submit a form on the new instance and check it goes through, then press Check again.