Companion code for this post: https://github.com/ImaginaryLandscape/deprecate_cmsplugin_filer

Update: Earlier versions of this migration code didn't maintain the original cms plugin object IDs. That wasn't an issue for standalone plugins but resulted in missing content within djangocms-text-ckeditor plugins, where the IDs are hardcoded into the body field. This has been resolved as the original cms plugin objects are now deleted before creating new ones in order to use the existing IDs.

If you've been building projects using django CMS for any length of time, chances are you're familiar with Divio's cmsplugin-filer application which provided image, link, file, folder and video plugins for interacting with django-filer. And if you're here, chances are you're aware that cmsplugin-filer has now been deprecated in favor of their standalone djangocms-[picture/file/link/video] plugins. Unfortunately, for a production project that already has hundreds of these cmsplugin-filer objects, simply switching to the newer packages is no simple task. You really only have a couple options — switching over to a fork with the hopes that it will continue to be supported as future Django versions are released, or setting about to migrate all of your existing plugins. Here we'll walk you through the latter.

Let's start with a word of caution. This remains experimental code. Taking these steps will make irreversible changes to your database objects. It's highly recommended you run this on a development version of your project before modifying production data to identify any issues that may arise. At the least, make a backup of your database to allow restoring if needed.

In searching for an existing solution to this problem, you may have come across this gist from github user wfehr just as we did. While their solution only contains the migrations for picture, file, and folder plugins, it was an extremely helpful starting point for working out the migrations for the remaining link and video plugins. Essentially, what these migrations do is map the existing model fields to the new model fields, ultimately deleting the old objects before saving their replacements.

Things you'll want to evaluate before migrating:

• Consider any project-level template overrides you may have created for the cmsplugin-filer plugins. These customizations would of course have to be reimplemented in the new djangocms-[file/link/picture/video] templates.
• If you currently are using django config settings such as CMSPLUGIN_FILER_IMAGE_STYLE_CHOICES or FILER_LINK_STYLES to manage image and link variations, you'll need to copy these as DJANGOCMS_PICTURE_TEMPLATES and DJANGOCMS_LINK_TEMPLATES, respectively. Note: there is a difference in behavior with FILER_LINK_STYLES and DJANGOCMS_LINK_TEMPLATES. The former would simply set a class while the latter expects a corresponding template to be created. Reference: https://github.com/divio/djangocms-link/#configuration

Migration steps:

1. Before running the migration, you can run the following command to make sure you back up the old plugin tables for quick restoring if needed.

   python manage.py dumpdata cmsplugin_filer_file cmsplugin_filer_folder cmsplugin_filer_image cmsplugin_filer_link cmsplugin_filer_video > ~/cmsplugin_filer.json

2. Ensure you've installed the new plugins, added them to INSTALLED_APPS, and migrated:

   pip install djangocms-file djangocms-link djangocms-picture djangocms-video

   INSTALLED_APPS += ( 'djangocms_file', 'djangocms_link', 'djangocms_picture', 'djangocms_video', )

   python manage.py migrate

3. I recommend also running the following command before and after the migration to get an inventory of the site's plugins and ensure they've all been migrated.

   python manage.py cms list plugins

4. Now the small app with the migration can be installed and run:

   pip install deprecate-cmsplugin-filer

   INSTALLED_APPS += ( 'deprecate_cmsplugin_filer')

   python manage.py migrate deprecate_cmsplugin_filer

5. If you once again run the following, you should see the cmsplugin-filer objects have been converted to djangocms-[file/link/picture/video] objects.

   python manage.py cms list plugins

6. Do a spotcheck of plugins on the site. This is where you may see errors to be corrected related to previous FILER_LINK_STYLES that are now expecting corresponding templates to be created for each style.

That should be it. Once you're satisfied everything is working, you can remove the cmsplugin-filer and deprecate_cmsplugin_filer modules from the project. Feel free to let us know if you come across any problems or have an improvement to suggest in the GitHub repo by creating an issue or filing a pull request.