Skip to main content

Freeform Migration Utility

​IMPORTANT

For the purpose of clarity in this documentation resource, any prior version of Freeform (free) and Freeform Pro 2.x, 3.x 4.x, 5.x and 6.x are referred to as Freeform Classic. The new version of Freeform is referred to as Freeform Next.

It's important to note that Freeform Next is not just merely an update or even an overhaul of Classic Freeform. It was completely rewritten from scratch, and built without attempting to conform to legacy requirements. Because of this, Freeform Next is a completely different add-on with its own namespace / folder name, allowing you to install it alongside Freeform Classic. In order to migrate your Classic data, you'll have to use this migration utility. And because not everything is the same in Freeform Next, not everything can be migrated. This page will go into details on what to expect, and how you might need to prep your site before attempting migration, and then what to clean up afterwards.

You must have the appropriate EE-compatible version of Freeform Classic installed and upgraded for Freeform Next to properly detect and migrate it. For example, if you moved from EE2 to EE4, but only have the EE2 version of Freeform Classic (4.x) installed, the migration won't work correctly. You'll need to update to the 5.x (EE3) or 6.x (EE4/EE5) version of Freeform Classic first. If you're switching from Classic to Freeform Next, we don't expect you to pay an upgrade fee to access the EE3 or EE4 compatible versions of Classic to only use it for 15 mins to run the migration utility, so feel free to temporarily "borrow and reuse" a newer Classic license from another site if you have, or contact us for a temporary copy.

​Quick Overview of Limitations

We figured it'd be helpful to place some of the large limitations of the migration utility at the start, so you could quickly see if migration is currently an option for you.

  • Your Next install needs to be fresh and untouched. The migration will overwrite any of your existing Freeform data. If you have modified your Next install (created fields, etc) and you don't mind losing the data, you can reinstall Freeform Next to run the migration.
  • Classic Freeform fields that are loaded with Channel Entry data will be migrated over as empty fields, as support for this does not yet exist in Freeform Next.
  • Manually built EE Template based forms will be loaded into a new Composer-based form for Freeform Next, as all forms are now setup inside Composer.
  • Composer Templates (formatting templates for Composer-based forms) in Classic will not be migrated over. Freeform Next has these as well, but the templating syntax is much more improved and very different.
  • File Upload fields with multiple files will be converted to having a single file upload input that can select multiple files at once (rather than showing multiple inputs).
  • All associated member data in Classic will not be migrated over, as Freeform Next does not currently store any of that information.
  • Currently not compatible with Multiple Site Manager (MSM). The migration will only migrate Classic data from Site 1. A future version might allow MSM compatibility.
  • If something goes wrong with the migration, it will only affect your Next install. This means it's fairly low risk to attempt the migration, as a failed migration can be resolved by reinstalling Freeform Next and trying again (perhaps after a bug fix, or something in Classic adjusted).

​Fields

All fields will be attempted to be migrated over to the appropriate field equivalent. However, there will be some exceptions to this as follows:

  • Email fields: Freeform Next contains a special Email fieldtype that is like regular input fields, but includes an option to assign an email notification to it. The following Classic fields will be converted to Email fields (and cannot be undone):
    • All fields that contain the string email in it's label or short name.
    • All Text fields that contain the Field Content Type of Email.

    If you want to make sure fields are designated as Email fieldtype, be sure they fall into the options listed above. If you do NOT want some fields to be converted to Email fieldtype, be sure to rename (temporarily for migration) or reassign your fields' Field Content Type.

  • Multi-select fields: while there is a Multi-select fieldtype in Freeform Next, the migration does not account for this.
    • All Classic Multi-select fields will be converted to Checkbox Groups.
  • Country / State / Province Select fields: there isn't a concept of field types like this in Freeform Next. While there is support for Data Feeders on Checkbox group, Radio group, Select and Multi-select fieldtypes in Freeform Next, the migration will NOT automatically convert your existing fields to this new style.
    • All fields of this type will be converted to Select fields with those existing data options populated as their options.
    • A new field option called Data Feeders is available for Checkbox group, Radio group, Select and Multi-select fieldtypes.
      • You can populate these fields with Entries, Categories, Members, or one of our many predefined options: States, Provinces, Countries, Languages, Number ranges, Year ranges, Months, Days and Days of the Week.
      • Freeform Data Feeders also offer flexible control over formatting and/or which data fills option labels and option values.

The following mapping of data will happen for each field during migration (Classic → Next):

  • Field type → Type
  • Field Label → Label
  • Field Name → Handle
  • Description → Ignored
  • Show field on submissions CP page? → Ignored
  • Show field on moderation CP page? → Ignored
  • Allow field to be used in Freeform Composer? → Ignored
  • Add To Form(s) → Ignored
  • Field type Settings:
    • Classic allows a variety of ways to place the data for options:
      • List (labels only) → List of Labels
      • Value/Label List → List of Labels and Options
      • Load from Channel Field → Ignored
      • Newline Delimited Textarea → List of Labels
    • File Upload fields:
      • Allowed upload count → File Count
      • File Upload Location → Upload Directory
      • Allowed File Types (string) → Allowed File Types (checkboxes)
      • Overwrite On Edit → Ignored
      • Disable XSS Clean → Ignored

​Email Notification Templates

Email Notification templates are different in Freeform Next, but the migration will bring them over, attempt to do some basic syntax updating, and attempt to map notification templates to forms (for Admin notifications). Be prepared to check this over after and update as necessary.

The following mapping of data will happen for each Email Notification Template during migration (Classic → Next):

  • Label → Name
  • Name (aka short_name) → Handle
  • Description → Description
  • Subject → Subject
  • From Name → From Name
  • From Email → From Email
  • Reply To Email → Reply-to Email
  • Include Attachments → Include Attachments
  • Word Wrap → Ignored
  • Allow HTML → Ignored (all emails are HTML)
    • Migration will attempt to make some basic string find/replace, but you'll want to check things over after the migration:
      • {all_form_fields}{/all_form_fields} → {form:fields}{/form:fields}
      • {field_label} → {field:label}
      • {field_data} → {field:value}
      • {entry_date format=""} → {date_created format=""}
      • {freeform_entry_id} → {submission:id}
      • {form_label} → {form:name}
      • {form_name} → {form:handle}
      • {form_id} → {form:id}

​Formatting Templates

Formatting templates, or Composer Templates as they're called in Classic, are all stored in database, whereas Freeform Next stores only in HTML files. The template code is much more improvement and very different, so these will be excluded from migration and need to be rebuilt. Freeform Next includes several sample formatting templates including popular HTML frameworks to get you started.

​Statuses

Classic stores statuses in the Preferences page, whereas Freeform Next has an interface for creating and editing them (including colors). Any additional statuses (if present) in Classic preferences will be migrated over:

  • Classic status_name → mapped to Name and Handle, with gray color assigned.

​Forms

The biggest improvement to Freeform Next is the way forms are handled and the intuitive Composer interface. Freeform Classic allowed Composer-based forms and EE Template-based forms, whereas Freeform Next only offers Composer-based forms (though you can similarly built very manual forms if you still wish to). Because of this, the migration has a little more work to do, but it should get most of the work done for you.

Freeform Classic manual EE Template-based forms still have to have fields assigned to the form, so the Migration utility will know which fields to grab and assign to forms (and place into Composer). The following mapping of data will happen for each Form during migration (Classic → Next):

  • Form Type → Ignored
  • Form Label → Name
  • Form Name → Handle
  • Description → Description
  • Default Status → Default Status
  • Notify User → Ignored (now applied directly to Email fieldtype instead)
  • User Email Field → Ignored
  • User Email Notification Template → Ignored
  • Notify Admin → if YES, attempt to connect form the options below:
    • Admin Notification Template → Email Template
    • Admin Email Notification Email Address → Admin Recipients
  • Form Fields (if EE Template-based) → Inserted into Composer layout in order of how fields were set in Classic.
    • Migration adds a Submit button at the end of the Composer form.
    • Fields can of course be rearrange later as desired.
  • Form Fields in Composer interface (if Composer-based) → Inserted into Composer layout in position order from Classic.
    • Rows and columns will attempt to be respected.
    • Dynamic Recipients and User Recipients fields → Ignored (due to how things are different in Next - will have to be recreated manually.
    • Title block in Composer → Ignored
    • Paragraph block in Composer → Converted to HTML block
    • Page breaks in Classic → Converted to Page tabs
  • View Freeform Entry URL → Ignored

​Submissions

Submissions can be migrated from Classic as well. However, this is an optional step. If you wish to have your submissions migrated to Freeform Next, be sure to check the Migrate Submissions checkbox on the Migration utility page.

All field data will be mapped over. Some exceptions to this are:

  • Classic Freeform fields that are loaded with Channel Entry data will be migrated over as empty fields, as support for this does not yet exist in Freeform Next.
  • File Upload fields with multiple files will be converted to having a single file upload input that can select multiple files at once (rather than showing multiple inputs).
  • All associated member data in Classic will not be migrated over, as Freeform Next does not currently store any of that information.
  • Field Layouts (submissions list page) in Classic will be ignored and need to be recreated.

Migrated submissions will have a title of something like Legacy Submission #7 (Migrated). This is because Freeform Next introduces a title generating feature for submissions, based on your fields (e.g. Submission Title = {first_name} + {last_name}). The migration utility cannot guess what you might want your titles to be, so we used something obvious. These can manually be updated if you wish (but no way to retroactively update these unfortunately).

​Preferences

The preferences/settings are very different between Classic and Freeform Next. No action will happen here during migration, with the exception of migration of statuses.

​Permissions

Freeform Next currently does not have permission controls. A future version will, but until then, no Classic permissions will be migrated over.

​Clean-up

Once the migration utility has completed, review your forms, fields, notification templates and submission data to ensure everything is as expected.

If there are any issues you suspect are a bug, please let us know through a support ticket before proceeding any further. We may be able to resolve an issue and you can try running migration again.

Proceed to adjusting your forms, fields, notification templates, etc and update your EE templates to use Freeform Next template tags. You can install the demo templates included with Freeform Next to see everything in action right away. Refer to the Switching from documentation for more information.

It's recommended that you leave your old Classic install and its data in place until a few weeks after you've moved on with Freeform Next. That way, if something did go wrong along the way, we may be able to resolve a bug or issue, and then you can redo the migration.

Page Feedback