Migrating from Advanced Custom Fields

WPM Fields › Tools › Migrate from ACF copies what Advanced Custom Fields (ACF) holds into Mass Custom Fields:

• field groups, with their fields, settings and location rules;
• ACF options pages, post types and taxonomies;
• the saved values of posts (all post types), terms, users, comments and options pages.

The migration only reads ACF. It never changes or deletes an ACF field group, an ACF value or any other row ACF owns, so you can run it, compare both plugins side by side and deactivate ACF only when you are happy. If something goes wrong you can reactivate ACF and nothing is lost.

Before you start

• Back up the database. The migration creates tables and writes values. It does not touch ACF data, but a backup costs nothing.
• Keep ACF active while you migrate, if you can. Then ACF's own functions are used to read everything, including field groups that are saved in ACF's acf-json folder or registered in PHP. If ACF is already deactivated the plugin reads ACF's data straight from the database, which only finds groups, post types, taxonomies and options pages that were created in the ACF screens (they are stored as posts that ACF leaves in the database).
• ACF Pro fields need the right plan on this site. Gallery, flexible content and clone are advanced field types. Without a plan that includes them they are listed as not included in your plan and are skipped. See Plans and licensing. Repeater, group, tab and accordion are free.
• If ACF Pro is deactivated but the free ACF is active, repeater, flexible content and clone fields cannot be read (ACF itself does not load them). The report then says None of its sub-fields can be copied. Activate ACF Pro for the migration, or deactivate ACF completely so the database reader is used.

Step by step

1. Open WPM Fields › Tools and choose the Migrate from ACF tab. The page loads a report straight away: a dry run that reads ACF and writes nothing. It is refreshed every time you open the tab.
2. • If nothing is found, the page says No ACF data found.
   • The badge in the card header says ACF active or ACF inactive, and the blue notice says either Advanced Custom Fields 6.x is active. or Advanced Custom Fields is not active; its data is read from the database.
2. Read the Field Groups list. Every ACF field group has a checkbox (all ticked), a title and these badges:

The second line shows the key the new group will get, the number of fields, and how many objects have saved values, for example Key book_details · 6 fields · 120 posts, 3 users or No values stored.

3. Open Details on rows with a warning badge. It lists, in plain words:
4. • Field "Intro" (message) is not copied: Message fields only show text and store no value.
   • Location rule "block == acf/hero" is left out: Blocks are not supported as a location.
   • notes such as a select with several values becomes checkboxes, a key that had to change, or No location rule can be copied, so the group gets no location and its values are not copied. Add location rules and run the migration again.
4. Read the lists of Post types, Taxonomies and Options pages:

5. Untick the field groups you do not want. Post types, taxonomies and options pages are always included.
6. Click Start migration. A dialog asks Start the ACF migration? and repeats that ACF data is left untouched. Confirm with Start migration.
7. The definitions are created immediately. The values are then copied in the background, in batches (see Background tasks); you may leave the page. While it runs, a progress bar named Migration progress and the text N of M objects checked update every few seconds.
8. When it finishes, the card shows Migration finished (or Migration canceled) with Values of N objects were copied (M values)., a list of what was created or kept, and, if some values could not be converted, N values were skipped with the reason for each (the first 100 are listed).

Cancel, resume and run again

• Cancel migration stops after the current batch. What was already created and copied stays; the status becomes Migration canceled.
• If the background queue stops (for example the queue was cleared or WP-Cron is disabled) a Resume button appears after about five minutes without progress. It queues the batches again.
• You cannot start a second migration while one runs (A migration is already running.).
• The button reads Run migration again after the first run. See below what a second run does.

Running it twice

A second run is safe and is meant to be used, for example when editors kept working in ACF after the first run:

Rows are updated, never duplicated: a post has one row per group.

To copy only some groups, tick only those before starting. To pick up changed field definitions, delete the migrated group in Field Groups first (this also drops its table), then migrate again.

What is copied, exactly

Names and keys

Field types

Field settings

Field group settings

Location rules

ACF location rules and the plugin's are both "any of these sets, each set needs all its rules". A rule without an equivalent removes its whole set, so a group is never shown in more places than it was in ACF. The report lists every rule that was left out. If no set remains, the group is created without a location and its values are not copied until you add rules.

At most 20 sets are kept from one group.

Post types, taxonomies and options pages

• Post types and taxonomies: all labels, visibility, menu, rewrite, archive, capability, REST and "supports" settings that exist in both plugins. Icons: only Dashicons carry over. A post type whose name is reserved or invalid is listed as Cannot be copied.
• Options pages: title, menu title, parent, capability, icon (Dashicons), position, description, update button and updated message. Pages registered in PHP with acf_add_options_page() are included when ACF is active. Values are read from the option names options_{field name} (or the prefix of the page's custom post_id). A numeric post_id is not supported.
• When ACF is active, its own post types and taxonomies are registered right now, so the copies are created switched off (Will be created switched off) and keep working once you switch them on after deactivating ACF.
• When ACF is inactive, a post type and a taxonomy that refer to each other (the usual case) are created together in one run with their links intact: the checks know the names created in the same run, and a taxonomy keeps the post types created before it.

Values

Values are read from the standard places ACF writes them and copied into the new tables:

An object counts as having values of a group when ACF's own reference (_field_name pointing to the field key) is present. Other meta rows are never touched. Every value is converted and then checked by the new field type exactly as if it had been typed, so a value the field does not accept is skipped and listed (The value could not be converted and was skipped. or The value is longer than the column allows and was skipped.).

Conversions worth knowing:

The copied values go to the new field group tables only. They are not written to wp_postmeta.

Using both plugins at once

You can keep ACF active after migrating. The two plugins keep separate copies of the values:

• Anything an editor saves in ACF's boxes still goes to ACF's rows (wp_postmeta). Mass Custom Fields' write bridge deliberately leaves keys that ACF manages alone, so ACF keeps working. Edits made in ACF are not visible in the new table until you run the migration again.
• Anything saved in the new boxes goes to the new tables.
• If a group shows in both plugins on the same edit screen, editors see two boxes. Decide which plugin owns the fields before you let editors work again.

Before you deactivate ACF

Work through this list:

• The report shows no unexpected N not copied badges, and you read every note in Details.
  
• N values were skipped is empty or understood.
  
• Open a few posts, a term, a user, a comment and each options page and compare the values with ACF.
  
• Your theme and plugins no longer call ACF functions. get_field(), the_field() and the [acf] shortcode do not exist without ACF and a theme that calls them unguarded will fail. Use wpmcf_get_field(), wpmcf_the_field(), the [wpmcf_field] shortcode, {{ }} variables or the builder dynamic tags. See Developer API and Integrations. get_post_meta() with the field key keeps working for fields of migrated groups.
  
• Post types and taxonomies that were created switched off are switched on in Post Types and Taxonomies.
  
• Field groups created without a location got their rules.
  
• Block, widget and menu locations that ACF supported are replaced by what you use now.
  
• You have a recent backup.
  

When everything matches, deactivate ACF. Its data stays in the database, so you can switch back at any time.

WP-CLI

wp wpmcf acf report
wp wpmcf acf migrate --dry-run
wp wpmcf acf migrate --groups=group_5f3a1b2c4d5e6

The CLI runs the whole copy in the foreground. See WP-CLI.

Known limits

• Not migrated, and listed in the report: message fields, field types from other plugins, choice values that are not among the stored choices, repeater rows past 200, rgba colors, media and URL icons, archive URLs in Page Link, options pages with a numeric post_id, option names with a WPML language suffix, and widget or block values.
• Flexible content and clone fields are migrated (on plans that include them) with the limits above.
• Post types and taxonomies are always migrated together with the groups you pick: you cannot leave them out.
• Running the migration does not update field group definitions (see Running it twice).

Troubleshooting

"No ACF data found" although ACF is installed. ACF stores its definitions as posts. Groups defined only in an acf-json folder or in PHP are visible only while ACF is active. Activate ACF and reload the tab.

A field group got the key something_2. A group with the first key already exists. The report says so before you start.

A group migrated but no values arrived. Open its Details. No location rule can be copied... means the group has no location, so there is no table row to put values in. Add location rules in Field Groups, then click Run migration again.

The migration stays on "running". The queue is not processing. Open Tools › Scheduled Actions (WordPress) and run the wpmcf/acf/migrate action, make sure WP-Cron is not disabled, or click Resume. On servers without a working cron use wp wpmcf acf migrate.

Everything works in ACF, but the new box is empty on a post. The post had no ACF reference row (_field_name) for that field, which happens for values written with update_post_meta() outside ACF. Re-save the post in ACF, or copy the value with wpmcf_update_field().

Some values were skipped with "could not be converted". The new field type rejects what ACF stored, for example a choice that no longer exists, a deleted attachment or a post id of a trashed post. Fix the data in ACF and run the migration again.