How to upgrade an existing site to Open Outreach

Open Outreach is designed as a starting point for developing an organizational website. The most straightforward way to use Open Outreach is to install it from scratch. From there, you can selectively migrate in content from other sources, including one or more existing websites. Migrating data here might be as simple as copying and pasting several pages from an old site into the new Open Outreach site. For larger sites, it could involve writing custom migration scripts or using an existing Drupal module like Migrate or Feeds.

If you already have a Drupal website that has a considerable amount of content or a large number of users or has custom functionality you want to keep, you might want to try directly converting the site into an Open Outreach install. Doing so could save you a lot of time in migrating content, but it will also raise a number of challenges and is probably something you should try only if you have the skills needed to do troubleshooting and some custom data work.

Basic upgrade to Open Outreach

Here are basic steps to take to upgrade an existing Drupal site to Open Outreach. These are rough guidelines only. Because each site is configured differently, you're likely to run into additional complexities. But these notes should at least get you started in the right direction.

  1. Back up. Don't work with your current live site. Instead, create a copy of the site and its database and work with the copies.
  2. Update the site to the same Drupal 7 release as is used in the latest Open Outreach version. If your site is in Drupal 6, you'll need to upgrade to Drupal 7. See the <a href="http://drupal.org/node/548922">drupal.org documentation</a> for detailed upgrade instructions. Here is a synopsis of some of the key steps. Update your site to the latest version of Drupal 6 (core and contributed modules). Before upgrading to Drupal 7, disable and uninstall modules you know you won't be using in the new site. To help determine which modules to uninstall, you could review the list of modules included in the Open Outreach distribution, found in the download in the directory profiles/openoutreach/modules/contrib. If a given module is not in Open Outreach and you don't foresee needing its functionality on your new site, you may choose to uninstall it. Then do an update to Drupal 7 core. Also upgrade any custom (non-core) data that you intend to keep on your new site. At the very least, you'll likely need to <a href="http://drupal.org/node/1144136">migrate Drupal 6 CCK custom fields to Drupal 7 fields</a>.
  3. Download Open Outreach. Download and extract the latest Open Outreach release and copy your existing site's Drupal 7 version settings.php file and files directory to the sites/default directory in the Open Outreach install. This will point the Open Outreach site to your existing site database.
  4. Change your site's 'install_profile' variable to 'openoutreach'. To tell your site that it is using Open Outreach, you need to reset a variable in the 'variable' table. To do so, download and enable the Devel module and then run the following code at devel/php: variable_set('install_profile', 'openoutreach');. Alternately, you can reset the variable by running this command in your database: UPDATE variable SET value = 's:12:"openoutreach"' WHERE name = 'install_profile';.
  5. Run updates. Run update.php to update any contributed modules that were enabled on your existing site and that are also present in Open Outreach.
  6. Enable the Features module and the Open Outreach feature. Enable the Features module at admin/modules. Then navigate to admin/structure/features. Under the "Other" category, enable the Open Outreach feature. If you are prompted about orphaned dependencies, select "Leave enabled".
  7. Adjust the roles on your site. Open Outreach uses three custom roles: contributor, editor, and administrator. If any of these roughly correspond to existing roles on your site, delete the Open Outreach roles and rename the existing ones to use the Open Outreach names. For example, if your site has a role called "site administrator", delete the newly created "administrator" role and rename "site administrator" to "administrator". After adjusting the role names, visit admin/config/people/accounts, ensure the "administrator" role is selected as the "Administrator role", and save the form.
  8. Select and enable the features you want to use. At admin/structure/features, under the "Features" tab, enable features that you wish to use on the site. Recommended: enable the features one by one, so that you can note and respond to any errors. If you are prompted about orphaned dependencies, select "Leave enabled". For more information about these individual features, see the openoutreach.org site. See also the section below on "Assessing and preventing component naming conflicts".

Cleaning up your site

The steps above outline how to get Open Outreach minimally installed on an existing site. But you'll still have a lot of work to do to reconcile your existing site content and structure with what has been created by Open Outreach. Here are a few tips to get you started--but you should begin with the assumption that there will be lots more you'll discover and neec to fix.

  • Content types and fields. You may have existing content types on your site that overlap with those provided by Open Outreach. For example, if you have an existing content type called 'news', it might have a function very close to that of the 'article' content provided by Debut Article. To begin to use the Debut Article functionality, you could consider converting the existing 'news' content into 'article' content.
    • Download and install the Node convert module.
    • At admin/structure/node_convert_templates, create one or more templates for converting your content. Then use the admin/content page to filter for the type of content you are converting from, select the appropriate conversion from the "Update options", and apply.
  • Blocks and contexts. Open Outreach uses the Context module to position blocks. Your existing site may use the core Block module for this purpose, may use Context or some other tool, or may use a combination of tools for block placement. With Open Outreach blocks displaying as well as those enabled by your existing site, you may get more than you need or want. To address this, selectively disable blocks left over from your existing site. If they were custom blocks, you may wish to delete them.

Assessing and preventing component naming conflicts

Open Outreach is built using the Features module, which allows exporting configuration from a Drupal site - content types, fields, views, and so on - into code, so that it can be enabled on multiple sites. For components like content types and fields to be exportable, they need to have a "machine name"--a unique name that will be the same on every site they're enabled on. For example, a date-type field used to store the date of an event might have the machine name field_date.

If Open Outreach is installed from scratch, we can be sure that the components we're creating won't conflict with existing components on the site. But when we're converting an existing site into an Open Outreach one, there's the potential that a component we're creating has the same name as one that already exists on the site. In certain cases, such a conflict can cause a site error that's difficult to resolve.

The particular issue to watch out for is: the site already has a field with the same name as a field that will be created by Open Outreach and the existing field is of a different type than the Open Outreach one. Drupal is unable to change the type of an existing field, so this situation will trigger an error.

There's no totally easy way to determine if a feature will conflict with existing components on your site. For fields, try the following:

  • At admin/structure/features, click the "Rebuild" link for the feature you're looking at. Look for any fields listed under a heading "Fields". The names here are of field "instances"--the version of a field that's applied to a particular content type. What we're concerned with is the actual field name, which is the part at the end beginning 'field_'.
  • Ensure the Fields UI module is enabled. At admin/structure/types, click the "Manage fields" link for a content type and look for fields with the same name as one of the fields in the feature. If you find one, you have the potential for a conflict--an error will occur if the field types are different.

Wrapping up

Upgrading an existing site to use Open Outreach is more work than just starting fresh. It takes some planning and the willingness to work through some potential challenges.

If you're up for a few bumps, though, upgrading an existing nonprofit site to Open Outreach can get you the benefit of keeping your existing content and users while quickly ramping on a lot of great new functionality.