When/If to Migrate Relationships in Old Toolset Sites


May 29, 2018

Yesterday, we released a major update for Toolset with new post relationships. In this post we explain in what cases, and if at all, you should migrate existing sites to use the new schema.

What’s new

The new post relationship feature in Types 3.0 allows you to build one-to-one, one-to-many, and many-to-many relationships. It’s integrated with all of the Toolset plugins. This means that your relationships will appear in Views, you can choose related fields and build forms for related content.

The previous relationships stored connections in postmeta (custom fields). This new relationship stores connections in a dedicated table.

What are the possibilities for existing sites?

Types 3.0 includes a migration tool which will set-up the new relationships, based on the old relationships. It will copy all the setup data and all the actual connections. The purpose of this migration tool is to allow you to use the new relationship features on sites that you built before this development became available.

When you update Types to version 3.0, go to the Toolset -> Relationships page and you’ll see the following migration prompt.

Post relationship migration prompt in Types 3.0
Post relationship migration prompt in Types 3.0

You can run the migration or dismiss it. Running the migration can take a while because it needs to process all the posts that were previously related and connect them again through the new connections table. For example, on our own Toolset.com site, it took 2 hours to run (and it ran without problems).

Should I migrate?

For old sites that you already delivered and are working, there’s no real need to run this migration. The sites will continue working as before with the old relationships. Users will be able to keep connecting posts with the old schema. Of course, you will not get the new features, but chances are you don’t need the new features for projects that you already completed.

If you want to improve existing sites, this migration is for you. Previously, to implement many-to-many relationships, you had to go through intermediary posts. It works but was heavy on the CPU and database. The new relationships allow you to implement many-to-many connections conveniently and with little server load.

However, you’ll need to spend a bit of work to adjust your code to take advantage of the new relationships.

How to migrate

First, please make a copy of your site’s database. We’ve made many tests and the migration tool worked for us. It worked for us on all our production sites, as well as test sites. But, it’s a long and complex process and it may fail. So, please prepare a backup before you run it.

Go to the Toolset -> Relationships page and click the Run the migration button.

A dialog will appear, with some warnings and checks. Review and confirm all of them and start the migration.

You’ll see the migration tool working and working and working. When it’s done, you’ll get a summary of everything that it did.

Post relationship migration summary
Post relationship migration summary

After you’ve run the migration, the Toolset -> Relationships page will reload. It will display a list of all relationships and allow you to manage them. You’ll see the ones you previously created and you can create new ones.

The Relationships admin page, after running the migration

What about new sites?

New sites that you build with Types 3.0 (or with its betas) already use the new relationships schema. There’s nothing to migrate, so you’re all set.


If you have any questions, doubts or concerns, ask here and we’ll get back to you.


Comments 23 Responses

  1. I have a site with many to many relations with a intermediary post

    artist – appearance – stage

    Can this relations be migrated with this tool?

    • Yes, it can, but this will NOT automatically turn this arrangement into many-to-many with the new schema. It will still say as two one-to-many relationships. The site will continue working, but without using the new many-to-many features.

      To fully take advantage of m2m, you will need to:

      1. Turn the two parent/child relationships into one m2m
      2. Move the connections data
      3. Update your Views to query with the new m2m relationships

      We can help you with step (2), which may involve a lot of data. We can help you do it with a small dedicated script. If you’re interested, please write in our support and we’ll help.

  2. i use in my site the “advanced bulk edit” plugin to bulk relation classes to professors (many to one relation) . This is an amazing way i found as there is no option to bulk relate post to posts. The way i did it is by bulk editing the custom field “_wpcf_belongs_parent_id” and inserting there the professor id. How should i do such action in the new relationship format? thanks

    • Hi Meir

      Thanks for the feedback.

      I would need some mor details about how you used to do things, but I assume that you were using the built-in bulk edit feature in WordPress, If that is the case we do not have such a functionality right now.

      I am taking a note to manage this as a feature request. We will add it to our internal racking system and evaluate whether this can be done, how, and eventually when. Please understand that we can not include all features at once, and that we can not even include all features that everyone expects, but we will consider this for the future.


      • I am not using the built-in bulk edit feature od wp – i am using the plugin https://codecanyon.net/item/advanced-bulk-edit/19160617 – it works amazingly – and gave me a brillant way to bulk edit the _wpcf_belongs_parent_id – custom field giving me the best way to filter posts by name and than relation them all changing their _wpcf_belongs_parent_id to proper ID parent. So the question is – Is there a new custom post field in place of _wpcf_belongs_parent_id to be populated and define in this way who is the parent of specific posts? Thanks for all the amazing plugins – i use them in almost all my sites!

      • and what about the possibility of populating the wpcf_belongs_parent_id with the old procedure – and than re-migrate this posts to be “compiled” to the new relationship format? (as it is done with old posts relationsships)

        • Hi Meir

          Relatonships are no longer based on a custom field value, due to several reasons. One of them is performance. Another is that for advanced features like many-to-many relationships, or multiple different relationships between the same post types, they do not fit nor provide the needed amount of data.

          This means that a bulk-editing plugin that manages custom fields will no longer be useful for bulk managing relationships once you migrate your site to the new schema provided by Types 3.0.

          Likewise, the migration process is something that you need to run once, and that is all. Any new custom field created with the same key will probably not reate the relationship that you want, although it might highly depend on how this third pary plugin works: we provide a backwards compatibility layer that in fact hijacks the WordPress functions and acts upon it saving custom fields for a post, detects whether it matches an old relationship field name, and creates the new relationship automatically:

          So my best answer seems to be: please try to continue with your existing workflow for bulk updating relationships and see how it works. Please note that this legacy backwards compatibility layer will only work with relationship definitions created before upgrading to Types 3.0: any new relationship definition that you add afterwards will not be managed by it. You can see which relationships can be affected by visiting the Toolset -> Relationships page: those that can be managd with this legacy layer are the ones with a label that mark them as “legacy”.

          Hope it helps.

  3. Does the new update come with some updated documentation for developers? Specifically, I have some queries that rely on wpcf_pr_post_get_belongs() and I’m concerned that they’re not populating correctly anymore. Any changes there?

  4. Hi there,

    Is there any documentation regarding programaticaly managing post relationships.

    Eg the snippet below is triggered on CRED_save_data where I have a checkbox in a form that removes the post relationship between the post being edited and selected parent posts, leaving unselected parent posts remaining as parents.

    if( isset($_POST['remove']) ) {
    $belongs = get_post_meta($post_id)[' '];

    foreach (array_keys($belongs, $_POST['remove'], true) as $key) {
    delete_post_meta($post_id, '_wpcf_belongs_child_id' );
    if ( sizeof($belongs) > 0 ) {
    add_post_meta($post_id, '_wpcf_belongs_child_id', $belongs, false );

    $belongs = get_post_meta($post_id)['_wpcf_belongs_child_id'];


    Thanks – Mark.

  5. Hi Emir,

    What will be the Toolset strategy concerning the plugins evolution. As the new V3 will need to make some “adjustments” in old sites, will you continue to offer updated versions of the V2 inparallel?

    Otherwise, this means that one day or another, all sites built with Toolset will need to be migrated in the V3, which is not a good news if the new functionalities are not needed for those sites?
    This will result in time consumption for preparing and validating the V2 => V3 transition on previews sites that could live without V3 !

    Let me know

    • H Pat

      Thanks for the feedback.

      As a matter of fact, Types has been split in two different… “flavours”: basic, which will continue to be offered in the official WordPress repository, and the Types version we will offer for clients. The one in the official repository got an update today just to prepare the differences: we removed our own mechanism for updating the plugin, and we will probably keep on cleaning it from commercial-purposed code.

      Our plan is to support this free version, in terms of bugfixes and small compatibility updates, but regarding features it is pretty much complete as to what we will include. We think it is fair that paying customers can get the benefit of having developers devoted to extending what the plugin can do, and free users can still use a fantastic plugin that offers a nice GUI for creating and managing post types, custom taxonomies, and meta fields for posts, users, etc.

      The data schema for this free version is not changing, so the upgrade routine will always be an open option for anyone willing to get the paid version. But if a site can live without the v3 and the user is not willing to get a subscription, the plugin shoud continue working properly without any major issue.

      Hope that helps.


      • Hi Juan,

        Sound good !
        Just one additional point : when we speak of Types V2 update, what about the other plugins (Views, Cred …).
        For example, if I want to update an old site, I understand that for Types, I can continue to use the V2 version in the WordPress repository. But doing this, can you confirm that all other Toolset plugins will be fully compliant with updated V2 version, or do we have to use another branch of these plugins updates (like Types ?).

        • Hi Pat

          As a mattr of fact, we considered this during development. The major integration work we have been doing with Types v3 falls inside Views, especially the filtering and data displaying, and inside CRED, now named Forms, related to being able to generate relationships using frontend forms.

          In both cases, we kept the previous code mostly unchanged, and thos eplaces that we modified were to make it even better, more robust and more user friendly.

          This means that Tolset contains an internal “switch”. Not just Types, but Toolset as a whole, as a family. If you do not turn that switch on, which is migrating the Types relationships, everything will continue working as it used to work before even if you use our latest released versions of everything. We are beign careful and checking always which “flavour” of Types you are using so Views and Forms load what works with it.

          Our goal is to keep sites working as they did. Of course, we would love everyone to upgrade and migrate their data, because it opens the door to very powerful features, and of course we will be putting our efforts in expanding those new features even more (and little less in supporting the legacy relationships, which will get kind of frozen). But for the future, things should keep on working without any change whatsoever.


  6. Hi, I’ve got an unusual situation in that earlier on in my development, I uploaded the beta version of Toolset. It seemed to cause some issues elsewhere, so support suggested I go back to the production version, which I did. I’ve since largely completed the site and uploaded all of my artists and artworks and related them with _wpcf_belongs_parent_id.

    Now I’ve updated Toolset. I do not get the prompt to migrate. Instead the one to many relationship I created in the beta version appears to have restored, and my old relationships are gone.

    How do I go about restoring relationships without having to go through 264 Artwork posts to assign them to their Artist post?

    • Can you please open a ticket about it in our support? One of our supporters will need access to your database. We’ll check the status and help you manually modify the migration status, to trigger again what’s needed.

  7. I have been building a site locally with the previous version of Toolset. Just to be sure, will anything I have done so far be changed or lost by updating to the latest version even if I do not plan to migrate?

    • Nothing should change. However, as this is a very big update, I still recommend that you back-up your site before updating.

  8. Hello,

    We have just upgraded to version 2.3.2.

    However, now it still prompts to upgrade from free version 2.3.2 to paid version 3.0.1.



  9. Hello Amir,
    I have a site (www.impel.eu) with 3 many to many relations with 3 intermediary posts
    Projects – project-tools – Tools (links tools to projects and vice versa)
    Projects – project-topics – Topics (links topics to projects and vice versa)
    Topics – topics-tools – Tools (links tools to topics and vice versa)
    Can this relations be migrated with this tool?
    Will it be a lot of work?
    What would you advice, run the migration or dismiss it?
    And if I dismiss it, can I do the migration later eventually?

    • The migration tool will keep the 6 one-to-many relationships that you already have in the site. Everything will continue working as-is, if you’ve used Views to display the content. Only if you have your own PHP that displays the related content, some thing may break.

      If you can, I suggest to try it on a dev copy of the site and make sure that everything displays correctly after running the migration.