user's guide complete up to upgrade from tv2 to tv3

docs/user_guide/install_tripal/manual_install/install_drupal.rst

@@ -0,0 +1,177 @@
+Drupal Installation
+===================
+
+Database Setup
+--------------
+
+Drupal can use a MySQL or PostgreSQL database but Chado prefers PostgreSQL so that is what we will use for both Drupal and Chado. We need to create the Drupal database. The following command can be used to create a new database user and database.
+
+First, become the 'postgres' user:
+
+.. code-block:: bash
+
+  sudo su - postgres
+
+Next, create the new 'drupal' user account. This account will not be a "superuser' nor allowed to create new roles, but should be allowed to create a database.
+
+.. code-block:: bash
+
+  createuser -P drupal
+
+When requested, enter an appropriate password. Finally, create the new database:
+
+.. code-block:: bash
+
+  createdb drupal -O drupal
+
+We no longer need to be the postgres user so exit
+
+.. code-block:: bash
+
+  exit
+
+Software Installation
+---------------------
+
+We want to install Drupal into our web document root (/var/www/html).   Before we can install Drupal we must ensure that that we are allowed to add files into the /var/www/html directory.  Select a user account that will be the owner of all web files and change the owner of the /var/www/html directory to that user:
+
+.. code-block:: bash
+
+  sudo chown -R [user] /var/www/html
+
+Substitute [user] for the name of the user that will own the web files.
+
+
+.. note::
+
+  The apache web server runs as the user 'www-data'.  For security reasons you should chose a user other than 'www-data' to be the owner of the /var/www/html directory.
+
+Tripal 3.x requires version 7.x of Drupal. Drupal can be freely downloaded from the http://www.drupal.org website. At the writing of this Tutorial the most recent version of Drupal 7 is version 7.59. The software can be downloaded manually from the Drupal website through a web browser or we can use the 'wget' command to retrieve it:
+
+.. code-block:: bash
+
+  cd /var/www/html
+  wget http://ftp.drupal.org/files/projects/drupal-7.59.tar.gz
+
+.. note::
+
+  If you are using older version of Ubuntu the web root directory may be /var/www rather than /var/www/html and you may need to change the path accordingly.
+
+Next, we want to install Drupal. We will use the tar command to uncompress the software:
+
+.. code-block:: bash
+
+  tar -zxvf drupal-7.59.tar.gz
+
+Notice that we now have a drupal-7.59 directory with all of the Drupal files. We want the Drupal files to be in our document root, not in a 'drupal-7.59' subdirectory. So, we'll move the contents of the directory up one level:
+
+.. code-block:: bash
+
+  mv drupal-7.59/* ./
+  mv drupal-7.59/.htaccess ./
+
+If an index.html file is present (as is the case with Ubuntu installations) you can move it out of the way so that it does not interfere with Drupal by executing the following:
+
+.. code-block:: bash
+
+  mv index.html index.html.orig
+
+.. note::
+
+  It is extremely important the the hidden file .htaccess is also moved (note the second 'mv' command above. Check to make sure this file is there
+
+.. code-block:: bash
+
+  ls -l .htaccess
+
+Configuration File
+------------------
+
+Next, we need to tell Drupal how to connect to our database. To do this we have to setup a configuration file. Drupal comes with an example configuration file which we can borrow.
+
+First navigate to the location where the configuration file should go:
+
+.. code-block:: bash
+
+  cd /var/www/html/sites/default/
+
+Next, copy the example configuration that already exists in the directory to be our actual configuration file by renaming it to settings.php.
+
+.. code-block:: bash
+
+  cp default.settings.php settings.php
+
+Now, we need to edit the configuration file to tell Drupal how to connect to our database server. To do this we'll use an easy to use text editor gedit
+
+.. code-block:: bash
+
+  gedit settings.php
+
+Find the following line
+
+.. code-block:: php
+
+  $databases = array();
+
+and then insert the following array just after the above line:
+
+.. code-block:: php
+
+  $databases['default']['default'] = array(
+    'driver' => 'pgsql',
+    'database' => 'drupal',
+    'username' => 'drupal',
+    'password' => '********',
+    'host' => 'localhost',
+    'prefix' => '',
+  );
+
+Replace the text '********' with your database password for the user 'drupal' created previously.  Save the configuration file and close the editor.
+Files directory creation
+
+Finally, we need to create the directory where Drupal will have write-access to add files.  By default, Drupal expects to have write permission in the /var/www/html/sites/default/files directory.  Therefore, we will set group ownership of the directory to the group used by the Apache web server.  This will be the user that Drupal uses to write files.
+
+.. code-block:: bash
+
+  mkdir -p /var/www/html/sites/default/files
+  sudo chgrp [group] /var/www/html/sites/default/files
+  sudo chmod g+rw /var/www/html/sites/default/files
+
+Substitute [group] for the name of the web server's group.  In Ubuntu this is www-data in CentOS this is apache.The above commands creates the directory, sets the group ownership for group. and gives read/write permissions to the group on the directory.
+
+Web-based Steps
+---------------
+
+Navigate to the installation page of our new web site http://localhost/install.php
+
+.. image:: install_drupal.install1.png
+
+Ensure that Standard is selected and click **Save and Continue**. You will next be asked to select the language you want to use. Choose **English**:
+
+.. image:: install_drupal.install2.png
+
+Next, you will see a progress bar as Drupal is installed.
+
+.. image:: install_drupal.install3.png
+
+Once it completes, a configuration page with some final settings will be visible.
+
+.. image:: install_drupal.install4.png
+
+Here you will provide details appropriate for your site, including your site name and administrative password.  If you are experimenting with Tripal the following values can be used:
+
+- Site Information
+  - Site Name: Tripal 3.x
+  - Site email: Your email address
+- Site Maintenance Account
+  - Username: administrator (all lower-case)
+  - Email: Your email address
+  - Password: ********
+- Server Settings
+  - Default country: (wherever the site is located)
+  - Default time zone: (your time zone)
+- Update Notifications (both boxes checked)
+
+Now, click the **Save and Continue** button. You will see a message about unable to send an email. This is safe to ignore for the tutorial, but for a production site you will need that your server can send emails to a service provider. Now, your site is enabled. Click the link Your new site:
+
+.. image:: install_drupal.install5.png

docs/user_guide/install_tripal/manual_install/install_prereqs.rst

@@ -0,0 +1,38 @@
+Tripal Prerequisites
+====================
+
+Tripal v3.x requires several Drupal modules. These include  `Entity <https://www.drupal.org/project/entity>`_,  `Views <https://www.drupal.org/project/views>`_, `CTools <https://www.drupal.org/project/ctools>`_, `Display Suite <https://www.drupal.org/project/ds>`_, `Field Group <https://www.drupal.org/project/field_group>`_, `Field Group Table <https://www.drupal.org/project/field_group_table>`_, `Field Formatter Class <https://www.drupal.org/project/field_formatter_class>`_ and `Field Formatter Settings <https://www.drupal.org/project/field_formatter_settings>`_ modules.   Modules can be installed using the graphical Drupal website by clicking on the Modules link in the top adminstrative menu bar.  Instructions for instaling Modules via the web-interface can be found here:  https://www.drupal.org/documentation/install/modules-themes/modules-7. However, Drush can be quicker for module installation. The following instructions will show how to install a module using the Drush command-line tool.
+
+First, install the Entity module.  We will download the current version using the drush command. On the command-line, execute the following:
+
+.. code-block:: bash
+
+  cd /var/www/html/sites/all/modules
+  drush pm-download entity
+
+Typically for all module installation we should check the README for additional installation instructions. Next, enable the module using a drush command:
+
+.. code-block:: bash
+
+  drush pm-enable entity
+
+For basic Tripal functionality you must also enable the Views and CTools modules. You can specify as many module as desired on one line:
+
+.. code-block:: bash
+
+  drush pm-download views ctools
+  drush pm-enable views views_ui ctools
+
+Finally, Tripal works best when it can provide default display layouts.   To support default layouts you must also enable the remainig dependencies:
+
+.. code-block:: bash
+
+  drush pm-download ds field_group field_group_table field_formatter_class field_formatter_settings
+  drush pm-enable ds field_group field_group_table field_formatter_class field_formatter_settings
+
+Optionally, you can install the ckeditor module.  This module provides a nice WYSIWYG editor that allows you to edit text on your site using a graphical editor. Otherwise, if you need images or formatting (e.g. underline, bold, headers) you would be required to write HTML.   It is recommended that this module be installed to improve the user experience:
+
+.. code-block:: bash
+
+  drush pm-download ckeditor
+  drush pm-enable ckeditor

docs/user_guide/install_tripal/manual_install/install_tripal.rst

@@ -0,0 +1,128 @@
+Tripal Installation
+===================
+
+Before installation of Tripal, you must first have a working Drupal installation.  Please see the previous section of this tutorial for step-by-step examples for server setup and Drupal installation instructions.  After installation of Tripal, you may install any Tripal extension modules you may want.
+
+Download Tripal
+---------------
+
+The easiest way to download Tripal is to use the Drush command-line interface for Drupal.  If you do not have Drush please see the Drush installation section of this tutorial.  To download using drush follow these steps:
+
+- Chage directories to your Drupal installation
+- Execute the following drush command
+
+.. code-block:: bash
+
+  drush pm-download tripal
+
+Alternatively, you can download Tripal using the Drupal web interface as per the instructions provided on the `Installing modules <https://www.drupal.org/documentation/install/modules-themes/modules-7>`_ documentation at Drupal.org.  The Tripal project page at Drupal.org can be found here:  https://www.drupal.org/project/tripal.
+
+Apply Patches
+-------------
+
+A bug exists in Drupal related to the bytea data type in PostgreSQL. At the writing of this document, a fix is not yet incorporated into Drupal, but a patch has been provided. Execute the following commands to patch Drupal:
+
+.. code-block:: bash
+
+  cd /var/www/html
+  wget --no-check-certificate https://drupal.org/files/drupal.pgsql-bytea.27.patch
+  patch -p1 < drupal.pgsql-bytea.27.patch
+
+There is also a bug in the Drupal Views 3.0 code that prevents Tripal's administrative and search data views from functioning. The patch is provided within the tripal_veiws module. To apply the patch execute the following:
+
+.. code-block:: bash
+
+  cd /var/www/html/sites/all/modules/views
+  patch -p1 < ../tripal/tripal_chado_views/views-sql-compliant-three-tier-naming-1971160-30.patch
+
+Install Tripal
+--------------
+
+The process for enabling the Tripal modules is the same as for the **ctools** and **views** modules that were enabled previously. To install the Tripal package, enter the following command:
+
+.. code-block:: bash
+
+  drush pm-enable tripal
+
+Tripal v3 is designed to be data store agnostic, therefore any data store with a compatible module can be used.  By default, Tripal supports Chado and a Tripal Chado module is provided.  Perform the same steps as before to enable the Tripal Chado module:
+
+.. code-block:: bash
+
+  drush pm-enable tripal_chado
+
+There are two more important Tripal modules:  **tripal_ds** and **tripal_ws**. These modules provide default layouts  for content (tripal_ds) and RESTful web services (tripal_ws).  Neither of these modules are required, however without the default layouts content pages will be less attractive without manual organization.  With web services you can share the content of your site that will allow remote software developers to access data programmatically.  The Tripal Web Services module also will allow integration of data from other Tripal sites with this site.  To enable both default layouts and web services use the following command:
+
+.. code-block:: bash
+
+  drush pm-enable tripal_ds tripal_ws
+
+Returning to the website, a new **Tripal** menu item appears at the top in the Administrative menu. Clicking the **Tripal** menu item reveals the Tripal administrative menu which contains four sections:  Jobs, Data Storage, Extensions and Vocabularies.  Each section will be described later in this guide.
+
+.. image:: install_tripal.install1.png
+
+Because we have the Tripal Chado module enabled we will find a link to manage the Chado setup under the **Tripal → Data Storage** section.  Notice the warning message indicating the Chado installation cannot be found.  This is because the Chado schema has not yet been installed.  The Chado schema is not automatically installed into the relational database (i.e. PostgreSQL).  This is because Chado can be installed separately outside of Tripal and therefore Tripal does not try to overwrite it if it already exists.  It is left to the site developer to consciously install Chado.  To install Chado, navigate to **Tripal → Data Storage → Chado → Install Chado**.  For this User's Guide it is assumed that Chado is not installed.  Select the option to install Chado v1.3 and click the button Install/Upgrade Chado.
+
+.. image:: install_tripal.install2.png
+
+After the button is clicked a message will appear stating "Job 'Install Chado v1.3' submitted.". Click the jobs page link to see the job that was submitted:
+
+.. image:: install_tripal.install3.png
+
+The job is waiting in the queue until the Tripal jobs system wakes and tries to run the job. The jobs management subsystem allows modules to submit long-running jobs, on behalf of site administrators or site visitors. Often, long running jobs can time out on the web server and fail to complete. The jobs system runs separately in the background. In the example above we now see a job for installing Chado. The job view page provides details such as the name of the job, dates that the job was submitted and job status.
+
+Jobs in the queue can be executed using drush to manually launch the job:
+
+.. code-block:: bash
+
+  drush trp-run-jobs --username=administrator --root=/var/www/html
+
+As the installation of Chado proceeds, we should see output on the terminal console indicating the progress of the installation.  You should see output similar to the following:
+
+::
+
+  Tripal Job Launcher
+  Running as user 'administrator'
+  -------------------
+  2018-06-29 16:28:38: There are 1 jobs queued.
+  2018-06-29 16:28:38: Job ID 1.
+  2018-06-29 16:28:38: Calling: tripal_chado_install_chado(Install Chado v1.3)
+  Creating 'chado' schema
+  Loading sites/all/modules/tripal/tripal_chado/chado_schema/default_schema-1.3.sql...
+  Install of Chado v1.3 (Step 1 of 2) Successful!
+  Loading sites/all/modules/tripal/tripal_chado/chado_schema/initialize-1.3.sql...
+  Install of Chado v1.3 (Step 2 of 2) Successful.
+  Installation Complete
+
+We now see that the job has completed when refreshing the jobs management page:
+
+.. image:: install_tripal.install4.png
+
+Prepare Chado and Drupal
+------------------------
+
+To complete the installation of Chado we must prepare it for use with Tripal.  Notice in the screen shot above the message indicates that "Chado is installed by Tripal has not yet prepared Drupal and Chado....".  We must prepare Chado and Drupal before continuing.  To do this, click the link titled **prepare both Drupal and Chado**.  The following page appears:
+
+.. image:: install_tripal.install5.png
+
+To prepare the site click the button Prepare this site.   A new job is added to the jobs queue.  Jobs in the queue can be executed using drush to manually launch the job:
+
+.. code-block:: bash
+
+  drush trp-run-jobs --username=administrator --root=/var/www/html
+
+.. note::
+
+  Preparing Chado may take several minutes to complete.   This is because the Sequence Ontology is automatically downloaded and installed into Chado as well as a few other vocabularies.
+
+Set Permissions
+---------------
+
+Because we are logged on to the site as the administrator user we are able to see all content. However, Drupal provides user management and permissions tools that allows the site admin to set which types of users can view the content on the site. By default there are three types of users anonymous,  authenticated and the administrator. For this tutorial we want to set permissions so that anonymous visitors to the site can see the genomics content. To do this, navigate to **People → Permissions**. Here you will see permissions for all types of content.
+
+.. image:: install_tripal.install6.png
+
+Preparing Chado and Drupal in a previous step resulted in the automatic creation of some commonly used content types such as Organism, Analysis, Gene, mRNA, Map, Publication, and others.   You can control who can view, create, edit and delete these types of content  types, as well as set some administrative permissions if needed. On the Permission page, scroll down to the Tripal section.  Here you will see permissions that you can set per type of user:
+
+.. image:: install_tripal.install7.png
+
+Review these permissions and set them according to how you want content to be managed.   Typically, the administrator user receives all permissions, and anonymous and authenticated users receive 'View' permissions for all content types.  If you desire to create other types of users, Drupal allows you to do this by creating new types of roles.  For example, if you know that some users will be responsible for curating content, then you may add a curator role by clicking the Roles link in the top right corner of this permissions page.  After the new role is created you can return to the permission page to set the permissions accordingly.

docs/user_guide/install_tripal/upgrade_from_tripal2.rst

@@ -1,4 +1,193 @@
-Lorem Ipsum
-===============
+Upgrade from Tripal v2 to v3
+================================
 
-Lorem ipsum
+Step 1: Upgrade Tripal
+----------------------
+
+1. Please note the following before upgrading:
+
+  .. warning::
+
+    If you have created custom extension modules for your site please note that 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.
+
+  .. warning::
+
+    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.
+
+  .. warning::
+
+      Upgrade can only be performed using 'drush' command.
+
+  .. warning::
+
+    If you have made customizations to Chado you may encounter problems during the upgrade.  It is not recommended to ever change any of the existing tables of Chado. However, if you have and if you do encounter such issues, please use the Tripal Issue queue to request help: https://github.com/tripal/tripal/issues
+
+2. 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 ** Administrative > Configuration > Maintenance Mode** . Then click the **Put site into maintenance mode** checkbox and click **Save Configuration**. Additionally, there is a text area on this page that allows you to customize the message displayed to your users while your site is in maintenance mode.
+
+  .. image:: upgrade_from_tripal2.step1-2.png
+
+  You can also put your site into "Maintenance mode" using drush be executing the following command:
+
+  .. code-block:: bash
+
+    drush vset site_offline 1
+
+3. 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:
+
+  .. code-block:: bash
+
+    drush pm-disable tripal_core
+
+4. 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 version:
+
+  .. code-block:: bash
+
+    drush pm-download tripal-7.x-3.0-rc3
+
+5. Enable the tripal module
+
+  .. code-block:: bash
+
+    drush pm-enable tripal
+
+6. Enable the tripal_chado module
+
+  .. code-block:: bash
+
+    drush pm-enable tripal_chado
+
+7. 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:
+
+  .. code-block:: bash
+
+    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.
+
+8. (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.
+
+    .. code-block:: bash
+
+      drush pm-enable tripal_ds tripal_ws
+
+9. Tripal Daemon provides automatic job execution and was previously a trip is now part of the main Tripal. If you had Tripal Daemon installed with Tripal 2 and you would like to continue using it follow these instructions. First, disable the module and remove the module directory.
+
+  .. code-block:: bash
+
+    drush pm-disable tripal_daemon
+
+  Next remove the original tripal_daemon module from the sites/all/modules directory of your site.  If you have had the Tripal Daemon installed for Tripal 2 then you should have all the necessary prerequisites and you can simply re-enable the module:
+
+  .. code-block:: bash
+
+    drush pm-enable tripal_daemon
+
+  .. note::
+
+    Remember to restart the tripal_daemon once you have completed the upgrade.
+
+
+10. Return to your Tripal site, and click the link that appears for preparing Chado and launch the job.
+
+  .. image:: upgrade_from_tripal2.step1-10.png
+
+  .. note::
+
+    You may see the message "Please update the database using "drush updatedb" before continuing"  You can safely ignore this message and it should disappear after preparing Chado.
+
+11. Next, navigate to the permissions page at **Administration > People > Permissions** and ensure that all new Tripal permissions are set appropriately for your site roles.
+
+  .. note::
+
+    Tripal v3 adds a variety of new permissions so please check the permissions carefully.
+
+
+12. 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:
+
+  .. code-block:: bash
+
+    drush vset site_offline 0
+
+13. Software Upgrade Complete!  At this point your site is running Tripal 3. You currently have all your Tripal 2 pages (known as nodes) living happily inside your upgraded Tripal 3 site.  This is known as "legacy mode".  The upgrade process was designed to allow you to upgrade to Tripal 3 first and then migrate your "nodes" slowly to the new "entities" as you are able.  Migrating from nodes to entities provides greater flexibilty and access to newer Tripal 3 features.
+
+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 step 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 immediately.
+
+1. Navigate to **Administration > Tripal > Data Storage > Chado** and click on Step 2.
+
+  .. image:: upgrade_from_tripal2.step2-1.png
+
+2. Select an individual content type to migrate from the Tripal v2 Content Type drop-down.
+
+  .. image:: upgrade_from_tripal2.step2-1.png
+
+3. 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.
+
+4. 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.
+
+5. 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:
+
+  .. code-block:: bash
+
+    cd /var/www/html
+    drush trp-run-jobs --user=administrator
+
+6. 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
+
+  .. image:: upgrade_from_tripal2.step3-1.png
+
+2. 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.
+
+3. 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
+
+  .. image:: upgrade_from_tripal2.step4-1.png
+
+2. Once you have confirmed that you are happy with the Tripal v3 pages for a given content type, check the desired check boxes for that content type.
+
+3. 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.
+
+.. note::
+
+  If you are a developer of Tripal extension modules, then 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).
+
+Troubleshooting
+---------------
+
+1. For sites that have 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:
+
+  .. image:: upgrade_from_tripal2.troub-1-1.png
+
+  Make sure its machine-readable_name is 'full_html' and save the configuration.
+
+  .. image:: upgrade_from_tripal2.troub-1-2.png