Skip to main content
Theme

How-to

Resolve what the plan asks

A plan cannot be approved while something would stop the load. Each of those is listed at the top of the plan with the fixes that apply to it.

Every option, in plain words

Each thing to decide offers one or more of these options. On the plan, every option says what it does with that item's own database, field or file, and then what is kept, what is lost, and an example. The same words are here, so you can read them before you start.

  • Create it from the data. Makes a new database on the new site, shaped from the old records, and copies every record into it. It is a normal database the site's pages and forms can use, not a holding area for content that cannot move.
    Kept: Every record, and every value in it.
    Lost: Nothing. Its labels, groups and tooltips are not known, so the Insites admin shows its plain field names until you set them.
    For example: An old event_bookings database with 40 bookings becomes an event_bookings database on the new site with the same 40 bookings.
  • Copy its database too. Copies the database a form saves to, along with the form.
    Kept: The form, and every entry already saved in its database.
    Lost: Nothing.
    For example: A Contact us form saves to contact_requests. The form and its 25 saved enquiries will be copied, so new enquiries keep arriving.
  • Leave the field out. Copies the records, but not this one field.
    Kept: Every record, and every other field in it.
    Lost: Every value in this field. The report counts how many there were.
    For example: A contacts database has a fax_number field the new CRM has no place for. The contacts will be copied, and their fax numbers will not.
  • Make it a file column. Makes this text field a file field on the new site, and copies the file each row's text points to into that row.
    Kept: Every record, and each file, now one you can open in the Insites admin. The old text is kept in the migration's undo record, so Roll back puts it back.
    Lost: Nothing. A file that cannot be copied is named in the log, and Roll back puts its text back.
    For example: A careers database kept each resume as a file address in a text field. The field becomes a file field, and each resume is copied into it.
  • Rename it. Copies the values into the field the new site uses for the same thing, under its name.
    Kept: Every value, under the new name.
    Lost: Nothing, as long as the name you type is the right field.
    For example: The old site calls it mobile_phone and the new CRM calls it mobile. Type mobile and the numbers land there.
  • Leave the database behind. Does not copy this database or any record in it.
    Kept: The records stay on the old site until it is deleted. Your reason goes in the report.
    Lost: Every record in it, on the new site. A page, form or sign-in rule that reads it finds nothing there.
    For example: A test_imports database from a one-off import that nothing on the site reads any more.
  • Leave these user profiles behind. Copies the people, but not this kind of user profile.
    Kept: Every person, with their email, their password and their other profiles.
    Lost: This profile and everything it holds for each person. A sign-in rule or page that checks for it stops finding it, so people can be refused or see less after they sign in.
    For example: Leave out a newsletter_preferences profile nothing uses. Do not leave out a member profile the members' pages check before they let someone in.
  • Hide its values. Replaces every value in this field with a scrambled stand-in, so the real text never reaches the new site.
    Kept: The records, and every other field in them.
    Lost: The real value in this field: all of it, not only the part that looks like a key.
    For example: An api_key field holding live payment keys. The records arrive and the keys do not.
  • Keep it. Copies the value or the file exactly as it is.
    Kept: Everything, including what looks like a key.
    Lost: Nothing. The key now also exists on the new site.
    For example: A map key that only works on the site's own domain, or a made-up key in a help page.
  • Remove from the migration. Does not copy this file of the site's code.
    Kept: Every other file. The report names this one, with your reason.
    Lost: This file, on the new site. A page, email or form that uses it breaks or is missing until someone adds it there.
    For example: An old test email nobody sends, or a page the new site already has at the same address.
  • Use the new instance's page frame. Changes the code to use the page frame (layout) the new site has for the same job.
    Kept: The pages, now inside the new site's frame.
    Lost: The old frame's name in the code. Anything the old frame showed that the new one does not is not there.
    For example: Pages that use the layout called application are changed to use default, the new site's name for it.
  • Remove the rule. Takes out a rule in your Transform choices that names a record the migration cannot find.
    Kept: Every record, copied the usual way.
    Lost: The rule. If it left a record out or changed a value, that no longer happens.
    For example: A rule that leaves out record 1234 of orders, when record 1234 was deleted on the old site.
  • Apply this fix. Copies the file with the change shown, so Insites v6 accepts it. The change does the same thing in a way v6 understands.
    Kept: The file, working the same way.
    Lost: Nothing. If you leave it unticked, the file will not be copied at all.
    For example: | push becomes | array_add, the v6 name for the same filter.
  • Replace with. Changes links to the old instance's own URL into the new instance's, in the code and the data.
    Kept: The links, now pointing at the new instance.
    Lost: Nothing. If you leave it unticked, those links break when the old instance is deleted.
    For example: An image at uploads.old-instance.example/photo.jpg is linked from files.new-instance.example/photo.jpg instead.

Not sure whether a database or a profile is needed? Ask whoever built the site before you leave it behind. A database copied with Create it from the data can be deleted in the Insites admin later, while something left behind can only be copied again with a final sync, and only while the old site still exists. This does not apply to a possible key: when in doubt, hide it.

When your reason argues against your choice

Some options leave something out: Leave the database behind, Leave these user profiles behind, Leave the field out, Remove from the migration and Hide its values. When the reason you give for one of them says the thing is needed, with words such as required, need, necessary, must, used in, important, crucial or keep, Apply asks Are you sure? first. It shows your reason and what will be lost. Press Change my choice to go back and choose another option, or Yes, apply it as chosen if the thing really is not needed on the new site. The decision log notes that you confirmed it.

For example, leaving a member profile behind with the reason This is required for login is asked about, because the members' pages check that profile before they let someone in. A reason that says the opposite, such as not required, no longer needed or nothing uses it, is not asked about.

Each option says what it does before you choose it. Choose one for every item. When an item has only one option, it shows as a box to tick: tick it to confirm, and untick it to take the choice back. Write why in a sentence a reader of the report can act on. Why you chose this is marked required: a reason is filled in for you only where the plan itself proves it. Nothing changes while you choose, and your choices are kept if you reload the page.

When you have decided, press Apply. Every choice is applied together and the plan is rebuilt one time with all of them. Anything you ticked on the Fixes page is applied in the same Apply, so tick those first. Each press of Apply rebuilds the plan, so deciding everything before you press it means one rebuild. If one choice cannot be applied, none are, and the page says which. Until you press Apply, Approve the plan stays held and says to apply your choices on the Summary page first. Each plan is kept in the Plan log, as Plan 1, Plan 2 and so on, so a new plan never replaces an old one.

Applying writes nothing to the new instance. Apply saves your choices into the plan and builds the plan again, which only reads the two instances. The same is true of the choices on every other page of the plan and of the Transform pages. Nothing is written to the new instance until you start the load on the Load step and type the plan's code. A dry run writes nothing at all unless you turn it into a migration and load it.

Hide its values replaces the whole value, not only the part that looks like a key. When a key was found inside long text, such as a page of documentation, the option says how long the value is: hiding it blanks that text on the new site, so keep it instead if the key is only an example.

The new instance's CRM is too old for the moved emails

Every moved email sends from the new instance's sender in Insites Console, through the CRM module, which needs CRM 6.1.2 or later. On an older CRM those emails would not send, and nobody would be told. So the plan names the CRM version and stops. Update the CRM module on the new instance in Insites Console, then plan again. How a moved email's sender is chosen.

A rule that matches nothing

A rule that leaves out a single row, or fixes one value, must name a row the migration copies. One that matches nothing stops the plan and says why in plain words: the table is not in the migration, or the row is not in the table. A row is named by its id. On a website such as Webflow or Squarespace, a row can be named by its id on the old site. On a final sync, which reads only what changed, a rule whose row did not change is a note, not something to decide.

Rows the new site already holds under another row's id

When a table is copied onto a new site that already holds rows, a row there can carry one of the source's ids as its external id. That is how the new site finds a row an earlier load gave a new id. If the row carrying it is a different row, the source's row cannot load: given a new id it would be written over that row, and at its own id the new site refuses it. The same is true when a row of another table carries the id, because an external id belongs to one row on the whole site. The plan names those rows, with their ids and the table that holds them, and stops. Choose Leave the database behind, or clear those external ids on the new site and plan again. The load checks again before it writes, in case the new site changed after the plan.

Worth knowing

Under Worth knowing the plan lists what does not stop the load but is worth reading first. Read these before you confirm. The first two are limits of this version of the tool:

  • More than 250,000 rows, or 165 MB of data. A step holds the rows it works on in memory, and that is the most this version has been measured copying. As the plan says, ask Shane at Insites before going ahead. Over 347 MB of data the plan stops instead: leave some tables out on the Transform step, or ask Insites to split the migration into parts.
  • A rollback of more than 1,000 people. When the load would create more than 1,000 people, a rollback could stop part way and leave some of them behind. As the plan says, ask Shane at Insites before going ahead.
  • Constants that could not be read. If the tool could not read the old site's constants when it captured it, none are copied, and the INVENTORY check fails on them. Read the source again to carry them.
  • A file column that holds an address as text. A column meant for an uploaded file sometimes holds an address written as text instead. The plan names the column, how many rows and an example. The address is copied as it is, and the file it names is not copied, so copy those files yourself before the old site is switched off.
  • A file column that still holds text from an earlier load that stopped. The plan names the column and how many rows. The load clears that text first (it is saved, so Roll back puts it back), then copies each file from the old site into its row.
  • Owners nobody copies. When a row's owner, or a column that names a person, is someone the migration does not copy, the plan names them by table. Those rows arrive with no owner rather than with a number that names somebody else on the new instance. Copy those people too, or accept it.

Jobs for after the load

  • Site settings that differ. A site's config.yml settings, such as liquid_raise_mode and string_interpolation, change how its Liquid runs, and no admin API sets them, so they are not copied. The plan reads them on both instances, and the To do list names each one that differs, with its value on each side. Blank, false, default and not set count as the same, and a setting for a feature the site's code does not use is left out. Set a value on the instance itself, or in the repository only if it already has app/config.yml: deploying config.yml replaces the whole file. If either instance's settings could not be read, the job asks you to compare them yourself.
  • A module's private files. The admin API lists only a module's public files. Each module of your own is named under Left behind, with the step: deploy its private files to the new instance from the module's own repository with the Insites CLI, then plan again or run a final sync.

Decisions your changes settled

When a new plan no longer asks you to decide something the previous one did, the plan says so at the top: each earlier decision, marked resolved, with the rule that settled it. That is how you can tell a change you made in the transform did what you meant.

Code v6 will not accept

Some Liquid that v5 accepts, v6 refuses. Where the tool knows the equivalent, it shows the change line by line and applies it when you tick Apply this fix and apply your choices. Choose every fix the tool can make ticks them all:

  • | push becomes | array_add
  • | to_i becomes | plus: 0
  • | to_s becomes | append: ''
  • A text in quotes that ends in a backslash, such as '\', gets its backslash doubled, '\\'. On v6 a backslash escapes the quote after it, so the text would never end.
  • A text in quotes that holds two or more backslashes in a row, such as '\\', loads on v6 but means something else, because v6 reads two backslashes as one. The plan names the file as a warning, and the fix doubles each run, so v6 reads the same text the old site did.
  • A page with a form that is marked searchable becomes not searchable. Searchable decides whether the instance's own site search reads the page, and Insites shows no form on a page it reads. A page that is not searchable is also left out of /sitemap.xml.
  • On a move to v6, a page that uses content_for or include_form, itself or in a partial it shows, is copied not searchable, because v6 refuses such a page while it is searchable. Each one is listed on the plan's Changes under Pages made not searchable for v6. Visitors see the page as before.

fetch_schema has no v6 equivalent: fix that file yourself on the source, then plan again.

When the new instance has string_interpolation switched on in its config.yml, a text in double quotes inside a Liquid tag that holds {{ }} is filled in there, where the old site showed it as written. The plan names each such file, and offers to change those texts to single quotes, which always show it as written. A text that holds a single quote or a backslash is named but not changed: change it yourself. A new instance without that switch, which is every one measured so far, gets no such finding.

The Fixes step

The Fixes step opens with what it needs from you. When it says Nothing to do on this page, go on: what it lists is for you to know. Otherwise it names each choice, and each finding carries a mark that says what to do. Every mark.

Links to the old instance

Code and content sometimes link to the old instance's own URL, most often the file storage URL its uploads are served from. After the old instance is deleted those links break. Ticking Replace with rewrites them, when you apply your choices, to the new instance's, in code and data. The site's custom domain moves to the new instance at cutover, so it is shown but never rewritten.