Upgrade from Tripal v2.x to v3.x

Page Sections

Note: Deprecated API functions from Tripal v1.x have been removed from Tripal v3. Therefore, use of deprecated API functions in templates or custom modules may cause a white screen of death (WSOD). Check the server logs if this occurs to find where deprecated functions may be used. 
Remember to perform a full backup prior to any upgrade. It is recommended to test upgrade on a copy or development version of your site prior to performing on the production site.

Step 1: Upgrade Tripal

Note: Upgrade can only be performed using 'drush' command.

  1. Put the site in maintenance mode.
    Before completing any upgrade you should put your site into "maintenance mode". This ensures that users are isolated from any temporary error messages generated through the process. To put the site in maintenance mode, navigate to Configuration > Maintenance Mode using the Administration toolbar. Then simply click the "Put site into maintenance mode." checkbox and click "Save Configuration". Additionally, there is a textarea on this page that allows you to customize the message displayed to your users while your site is in maintenance mode.

 

You can also put your site into "Maintenance mode" using drush be executing the following command:

drush vset site_offline 1
  1. Disable tripal modules.
    Before updating the Tripal codebase, you should disable all Tripal modules. This ensures that Tripal is not actively trying to access files that you are changing, as well as, clears any cached information for these modules. When using drush, disabling the core module will disable all other Tripal modules:

    drush pm-disable tripal_core
  2. The Tripal modules must also be downloaded and updated. To do this, delete the old Tripal v2 modules directories (be sure you have a backup before removing). The following command will retrieve the Tripal 3.0-rc1 version:
    drush pm-download tripal-7.x-3.0-rc1
  3. Enable the tripal module
    drush pm-enable tripal
  4. Enable the tripal_chado module
    drush pm-enable tripal_chado
  5. Enable Tripal v2 Legacy modules
    Tripal v2 modules are now called 'legacy modules'. these are the modules that were disabled in step #2. For backwards compatibility, you should re-enable these modules:
    drush pm-enable tripal_core, tripal_views, tripal_db, tripal_cv, tripal_analysis, tripal_organism, tripal_feature, tripal_pub, tripal_stock

    Be sure to enable any additional modules not included in the example drush command above. The easiest way to ensure you have re-enabled all the modules disabled above is to copy the list drush provided when asking you to confirm disabling tripal_core above.

  6. (Optional but Recommended) Enable the Tripal DS (provides default themeing for Tripal 3.x) and Tripal Web Services.
    Tripal DS: Tripal 3.x provides complete integration with Drupal's Display UI allowing you to re-order fields and customize display using Drupal Extension modules. The Tripal DS module provides Tripal Panes similar to those in Tripal 2.x (except that more then one pane can be open at a time) and groups fields by default to make the display less overwhelming.
    Tripal Web Services: Tripal Web services provide a way for Tripal sites to share data with each other and with their community in a programmatic manner. Your web services will show the same content available through your Tripal site using the RDF Specification.
    drush pm-enable tripal_ds tripal_ws
  7. Return to your Tripal site, and click the link that appears for preparing Chado and launch the job.

  1. You can now bring your site out of maitenence mode.
    This can be done by either reversing the your actions through the interface in #1 or through drush with the following command:

    drush vset site_offline 0

At this point you will have all your Tripal 2 nodes living happily alongside your Tripal 3 entities. The upgrade process was designed this way to allow you to upgrade to Tripal 3 slowly on a per content type basis, since content types with more customizations may take more effort to upgrade then others.

Step 2: Migrate Content

The process allows you to create Tripal 3 content types exposing the same data as your Tripal 2 nodes. Data is not duplicated as it resides in Chado but rather mappings are made between Chado records and your new Tripal 3 entities just as they were made to Tripal 2 nodes. This process will not remove or destroy existing Tripal v2 nodes/pages but will create new Tripal v3 entities/pages.

This allows you to keep existing pages while reviewing and customizing the Tripal v3 content types. Site visitors can continue to visit the Tripal v2 pages. Tripal v3 content types may remain private while customization is underway. Once customization is completed a subsequent step will allow you to swap out Tripal v2 pages for the newer Tripal v3 pages. Once this step is complete, you will also be able to expose your data via Tripal 3 Web Services immediatly.

  1. Navigate to Administration > Tripal > Data Storage > Chado and click on Step 2.

  1. Select an individual content type to migrate from the Tripal v2 Content Type drop-down.

  1. Click the 'Get Tripal v3 Types' button to retrieve a list of Tripal v3 content types to which this Tripal v2 type can be converted. This may take a while depending on the size of your database.
  2. Select the checkbox beside each Tripal v3 type you would like to create. The number of entities/pages that will be created for that content type is shown in brackets beside the name.
  3. Then click the "Migrate [Tripal v2 Type]" button. This will submit a Tripal job to create the requested content. Submit this job manually on the command-line as follows:
    cd /var/www/html
    drush trp-run-jobs --user=administrator
  4. Now repeat 1-5 for each content type. Since this step simply creates new Tripal v3 content without touching the existing Tripal v2 content, there really is no reason not to migrate all your content types. Especially since the Tripal v3 content remains private and thus hidden from your users.

Step 3: Use Legacy Templates (optional)

This step is completely optional and not necessarily recommended. It was provided to aid the upgrade process for Tripal sites with lots of customizations who may not have the developers or time to create new Tripal 3 fields to replace their old templates.

All customizations involving re-ordering or re-naming of existing fields can now be done through the Drupal "Manage Fields" Admin interface found under Administration > Structure > Tripal Content Types > [Type you are interested in] > "manage fields". You can also use this interface to switch from Tripal Panes to a long listing of content, fieldsets, tables, tabs, accordions, etc. I suggest playing around with this new interface and looking into Drupal Field Group and/or Display Suite to explore your options for customizing page display through the interface, since this will ease the transition to Drupal 8. 

That said, if you decide to stick with your current customized templates, the following instructions will show you how. Keep in mind this is done on a per content type basis allowing you to do use the new interface on less customized content while still relying on your templates for highly customized content.

  1. Navigate to Administration > Tripal > Data Storage > Migrate and click on Step 3

  1. Click the checkbox for the Tripal v2 content types you want to keep your old templates for. Unchecked content types will use the new Tripal 3 interface.
  2. Click Save.

Step 4: Delete Tripal v2 Content and Publish Tripal v3 Content

This final step allows you to fully switch to Tripal v3 pages. You can move URLs and titles from Tripal v2 pages to their corresponding Tripal v3 pages. This ensures user bookmarks and external links to your site are not broken. Here you can also unpublish Tripal v2 content types or completely remove them if desired. You can perform these actions in stages such as first moving titles and URLs, then unpublishing Tripal v2 pages and once the migration has been verified you can finally delete the Tripal v2 pages to free space. Deleting the Tripal v2 content will not delete the data in Chado. The page is simply removed from the site.

  1. Navigate to Administration > Tripal > Data Storage > Migrate and click on Step 4

  1. Once you have confirmed that you are happy with the Tripal v3 pages for a given content type, check the desired checkboxes for that content type.
  2. Then click submit --This step cannot be reversed!

You have now completed the migration process and can safely disable the Tripal v2.x Legacy modules assuming no extension modules still depend on them. The Tripal API is completely backwards compatible so any extension modules that do not interact with nodes directly can safely be made Tripal v3.x compatible by changing the module to depend on tripal rather then tripal_core (can be done in the modules .info file). Congratulations, you now have a Tripal v3.x site!

 

Note for sites upgrading from Drupal 6 (i.e. field not shown after the migration):

If your site was upgraded from Drupal 6, you'll need to add a new text format with a machine name called 'full_html' as this is the default formatter that Tripal v3 uses. As in Drupal 6, the 'Full HTML' text format has a numeric machine name (usually '2') that was later changed to 'full_html' in Drupal 7.

To do this, go to 'Configuration' > 'Text formats' in your administrative menu and click on the 'Add text format' link:

Make sure its machine-readable_name is 'full_html' and save the configuration.