Installation Guide

ERcore Installation Guide

[September 16, 2013]

This document describes how to install ERcore V1.1 on a target system. The first section provides system requirements and a high level overview of the installation process. Subsequent sections provide more detail and include troubleshooting suggestions and common site customizations. The intended audience for this document are system administrators and ERcore developers.
Table of Contents

1 System requirements and installation overview

1.1 Server Requirements

ERcore is known to work with the following specific versions of Drupal 7 server components:
  • Drupal: 7.14 through 7.22
  • MySQL: 5.1.66-0+squeeze1, 5.1.58-1ubuntu1, 5.5.31-1.fc17.x86_64 (Fedora)
  • PHP: 5.3.3-7+squeeze15, 5.3.6-13ubuntu3.8, 5.4.16-1.fc17.x86_64 (Fedora)
  • Apache: 2.2.16 (Debian), 2.2.20 (Ubuntu), 2.2.23-1.fc17.x86_64 (Fedora)

1.2 A word about PostgreSQL

Drupal is described as supporting both MySQL and PostgreSQL as the underlying database storage engine. However, there appears to be a lag in supporting fixes to PostgreSQL problems in Drupal Core. This is just a word of warning for those who plan to use PostgreSQL instead of MySQL. More information about this issue can be found at:

1.3 PHP.INI parameters

Several PHP system parameters defined in php.ini can cause problems on the Apache target server when set too small. The following are suggested minimum values for two of these:
  • max_execution_time — set to 240
  • memory_limit — set to 256M.
These should be set in /apache2/php.ini prior to ERcore installation. If the drush utility is used, they should be set in /cli/php.ini as well.

1.4 Drupal module and callable library requirements

The following callable libraries are used by ERcore:
  • PHPExcel, v1.7.9
The latest version of the following Drupal modules are used by ERcore:
  • admin_menu
  • bundle_copy
  • calendar
  • computed_field
  • ctools
  • date
  • date_api
  • date_popup
  • date_repeat_field
  • date_views
  • entity
  • entity_token
  • entityreference
  • entityreference_cascade_delete (ercd)
  • entityreference_prepopulate
  • field_group
  • field_permissions
  • flag
  • libraries
  • link
  • markup
  • nodeaccess_userreference
  • page_manager
  • php
  • rules
  • rules_admin
  • rules_scheduler
  • select_or_other
  • views
  • views_content
  • views_data_export
  • views_php
  • views_ui

1.5 Installation summary

ERcore is a Drupal sandbox project and therefore requires a more complicated installation procedure than a Drupal full project. The following steps must be performed to install ERcore.
  1. Install PHPExcel library.



    On the target site, create a directory in DOCUMENT_ROOT/sites/all/libraries/ named /PHPExcel/. Download and decompress version 1.7.9 of the PHPExcel library. Copy the decompressed directory tree into the /PHPExcel/ directory on the target.
  2. Download prerequisite modules.



    Download latest version of Drupal modules listed in Section 1.4↑ using either the Drupal module interface or the drush utility download command.
  3. Install ERcore files.



    On the tags page of the ERcore git repository, click the hotlink for the desired ERcore version. On the resulting page, click snapshot to download the ERcore files in tar.gz format. On the target site, create a directory named /er/ in DOCUMENT_ROOT/sites/all/modules/. If the directory already exists, delete its contents. Decompress the ERcore snapshot and copy its contents to the /er/ target directory.
  4. Install ERcore module.



    In Drupal, enable the EPSCoR Reporting module in the EPSCOR section of the Modules page. A progress bar is displayed during the installation process, followed by an installation status page. Note that installation may take several minutes.
The remainder of this document describes installation in more detail and includes troubleshooting suggestions and common site customizations. Section 12↓ describes updating ERcore software to a new version.

2 Installation kits & their location

An ERcore kit, as defined in this document, is simply a compressed /er/ directory tree in tar.gz file format and which was downloaded from the ERcore git repository. The git software uses the term snapshot to refer to a compressed directory tree, so an ERcore kit and a snapshot from the ERcore git repository are essentially the same thing.

2.1 Recommended releases

ERcore recommended releases can be found and downloaded with the following steps:
  1. Navigate to the ERcore git repository url at
  2. Click Repository viewer under the Development header arriving at the Git Summary page. (It is not necessary to login to view the repository.)
  3. The section named tags at the bottom of the page lists the recommended releases for ERcore. The current recommended release for ERcore is version 7.x-2.x.
  4. Click the hotlink for the desired version of ERcore, taking you to the commit page for that tag.
  5. Click snapshot to download the compressed directory tree (installation kit) for that version of ERcore in tar.gz format.
It should be noted that the filename of this compressed file is computer generated and has no memorable relationship to the ERcore version number. An example snapshot filename is 1837936-bae76ad.tar.gz. You are encouraged to rename this file to something more memorable like erkit-v7.x-2.x.tar.gz. Note also that the top-level directory name within this compressed file also computer generated (e.g., 1837936-bae76ad) and not /er/ as one might expect.

2.2 Non-standard versions

In some cases it is necessary to install a non-standard version of ERcore on a target system, one that does not have a tag associated with it. Since the git repository for ERcore maintains snapshots for every committed change to the source code, any of these snapshots can be installed on a target system. The desired snapshots can be found with the following steps:
  1. Perform steps 1--2 above, arriving at the Git Summary page.
  2. The section named heads at the bottom of the page lists pointers to git source code branches. Currently there are 2 source code branches for ERcore: 7.x-1.x and 7.x-1.x-dev.
  3. Click the hotlink for the desired branch head of ERcore, taking you to the shortlog page listing all commits for that branch
  4. Identify which commit you wish to install on the target system and click snapshot to the right of that entry. This will download a compressed directory tree for that version of ERcore in tar.gz format.
  5. Alternatively, clicking commit to the right of the entry will take you to a informational page about the commit which also includes a timestamp. This page also allows you to download a compressed directory tree by clicking snapshot.
As with any snapshot from git, the downloaded filename is generated. You are encouraged to rename this file to something more memorable like er-v7.x-1.x-2013-03-15-2051.tar.gz.

3 Target location

In the description below, the mnemonics <target-modules> and <target-libraries> are used to represent the full path of the /modules/ and /libraries/ directories where ERcore and required libraries should be installed. These paths can be determined as follows:
<target-modules>   ::= DOCUMENT_ROOT/sites/all/modules/
<target-libraries> ::= DOCUMENT_ROOT/sites/all/libraries/
Where DOCUMENT_ROOT is defined by the target site Drupal web server. The correct value for DOCUMENT_ROOT can be determined from Drupal as follows:
  • navigate to the PHP Status page via ReportsStatus reportPHP (more information) (or http://<your-site>/admin/reports/status/php)
  • search for DOCUMENT_ROOT in the Apache Environment section on this page to determine the symbol’s value. A typical value for Turnkey appliances is /var/www/drupal7/.

4 Step 1: Backup target site

Prior to installing ERcore, it is strongly advised that you make a backup of key files on your target system. These include MySQL database, the /modules/ directory tree, the php.ini files, and any other important files. If something goes wrong with the installation of ERcore, you can restore your server with this backup. Use your favorite utility to perform this backup.
Ideally, the backup should be performed when no one is using Drupal. One way to accomplish this is with the following Apache commands to stop and restart the server:
apachectl -k stop
   ...do backup here...
apachectl -k restart

5 Step 2: Check PHP.INI parameters

Several PHP system parameters defined in php.ini can cause problems on the Apache target server when set too small. The following are suggested minimum values for two of these:
  • max_execution_time — set to 240
  • memory_limit — set to 256M.
The current values of these parameters can be determined from Drupal as follows:
  • navigate to the PHP Status page via Reports Status report PHP (more information) (or /admin/reports/status/php)
  • search for the above symbols on this page to determine their current values on the server
  • search for php.ini on this page to determine the location of the php.ini file if the parameters need modification. A typical location for this file is /etc/php5/apache2/php.ini
These two parameters should also be adjusted for command-line utilities on the target system (for the drush utility used in this installation procedure). This is accomplished by editing the php.ini file in /cli/ directory parallel to the /apache2/ directory.
Another PHP parameter that has proven useful on occasion is display_errors. If users of your site encounter a blank page without any error message (lovingly known as a White Page Of Death - WPOD), setting display_errors = On can sometimes help determine what the problem is.
If any changes are made to php.ini, the Apache server must be restarted to activate the changes. The following shell command does this:
apachectl -k restart

6 Step 3: Installing prerequisites

The ERcore package relies on approximately 20 underlying Drupal modules, each of which must be downloaded prior to installing ERcore. While this can be accomplished using the Drupal web-based interface, it is considerably faster to use the drush command-line utility to perform these downloads. In addition to the Drupal modules, an API library for Excel spreadsheets must also be downloaded to the target system. This section describes how to install these prerequisites on the target system.

6.1 PHPExcel Library download

This step can be done in numerous ways, depending on your Unix experience, preferences, and needs. This subsection however assumes you are using FileZilla (or a similar graphical file management tool) on a Windows machine. You will need a local temporary directory to decompress the PHPExcel kit into and you will need FileZilla windows to access this local temporary directory and the target system.
Perform the following steps to download the library kit to your local system and decompress it:
  1. Access http://phpexcel.codeplex.com/ in a web browser.
  2. In the Downloads section, click the hot link after Current release: (currently PHPExcel 1.7.9)
  3. Click hot link under Recommended download. Alternatively, the Code only (no Documentation) download may be used if PHPExcel documentation is not required on your site.
  4. Click save file to the local Windows machine, noting location
  5. Using Windows Explorer, select the local copy of this kit. Right-Click the file and select Extract All... to decompress the zip file to a local directory.

6.2 PHPExcel Library installation

In the description below, the mnemonic <target-libraries> is used to represent the full path of the /libraries/ directory where PHPExcel should be installed. This path can be determined as follows:
<target-libraries> ::= DOCUMENT_ROOT/sites/all/libraries/
Section 3↑ describes the definition of DOCUMENT_ROOT on the target system. Note that the /libraries/ directory is “parallel to” the /modules/ directory. Perform the following steps to install the PHPExcel library files to the target system from the kit downloaded in the previous subsection:
  1. Use FileZilla to login to the target site.
  2. In the FileZilla “remote site” pane, navigate to the <target-libraries> directory on the target system.
  3. Create the directory <target-libraries>/PHPExcel/ if it does not yet exist. This is the location where the PHPExcel library files will exist on the target system.
  4. In the FileZilla “local site” pane, navigate to the decompressed PHPExcel kit that was created above. The following two files should be in this directory: Classes (a directory) and changelog.txt.
  5. Copy the contents of this directory from local site into the /PHPExcel/ directory on the target system.
When finished, check that the following files exist at the target site:
DOCUMENT_ROOT/sites/all/libraries/PHPExcel/changelog.txt
DOCUMENT_ROOT/sites/all/libraries/PHPExcel/Classes/PHPExcel.php

6.3 Drupal module download

The drush command-line utility is used to update Drupal and to download required prerequisite projects and modules prior to installing ERcore. The following commands assume a standard Turnkey Drupal 7 appliance installation. If the target system directory tree is not structured as described above, change the cd command-line to meet your needs. See Section 3↑ to determine the directory tree structure of your target system. See Section 1.4↑ for the list of required Drupal modules.
Perform these commands on the target system.
cd DOCUMENT_ROOT
drush up
cd DOCUMENT_ROOT/sites/all/modules
drush dl bundle_copy computed_field ctools date date_api date_popup
drush dl date_repeat_field date_views entity entity_token
drush dl entityreference entityreference_prepopulate field_group
drush dl field_permissions flag libraries link markup
drush dl nodeaccess_userreference page_manager php rules
drush dl rules_admin rules_scheduler select_or_other views
drush dl views_content views_data_export views_php views_ui
drush en entityreference
If any of the above modules are already installed on your system, a warning message will be displayed. “No release history” warnings can also be ignored.
The last drush command listed above is required to prevent an error later in the installation process. It enables the entityreference module within Drupal prior to installing ERcore with the steps below.

7 Step 4: Installing ERcore files

This step can be done in numerous ways, depending on your Unix experience, preferences, and needs. However, this section assumes you are running FileZilla (or a similar graphical file management tool) on a Windows machine. You will need a local temporary directory to decompress the ERcore kit into and you will need FileZilla windows to access the target system <target-modules> directory. This section also assumes you have the 7-ZIP utility (or a similar decompression product) on the Windows system. If you are familiar with git commands, git clone or git pull may be used to install ERcore files on the target system as an alternative to the following steps.
Note that this section covers installing a fresh copy of ERcore on the target system. See Section 12↓ for updating ERcore software to a new version.

7.1 Downloading and decompressing ERcore kit

Perform the following steps to download the ERcore kit to your local Windows system and decompress it:
  • Select the appropriate git snapshot from the ERcore repository, as described in Section 2↑.
  • Download the ERcore kit ( the /er/ compressed directory tree) into a local temporary directory
  • Use the 7-ZIP utility to decompress the directory tree.
  • Note that the top-level directory has a generated name similar to /1837936-bae76ad/ instead of /er/. A directory named /modules/ and a file named er.module should exist in this directory.

7.2 Removing ERcore from previous install

If ERcore was previously installed on the target system, the following steps should be performed to remove that version from the system:
  • login to the target website as administrator
  • click Modules on the Drupal home page
  • scroll down to the EPSCOR section on this page
  • uncheck EPSCoR Reporting
  • click Save configuration at the bottom of the page.
Next, perform the following steps to remove the /er/ files from target system:
  • Use FileZilla to login to the target site.
  • In the FileZilla “remote site” pane, navigate to the <target-modules> directory on the target system.
  • Use FileZilla to delete the contents of the /er/ directory.

7.3 Installing ERcore files on target

Perform the following steps to install the ERcore files on the target system:
  • Use FileZilla to login to the target site.
  • In the FileZilla “remote site” pane, navigate to the <target-modules> directory on the target system.
  • Create the directory <target-modules>/er/ if it does not yet exist. This is the location where ERcore directory tree will exist on the target system.
  • In the FileZilla “local site” pane, navigate to the top-level directory of the decompressed ERcore kit that was created above. There should be a number of sub-directories and files here including the files /module/ and er.module.
  • Copy the contents of this top-level directory from local site into the <target-modules>/er/ directory on the target system.
When finished, check that the following files exist at the target site:
DOCUMENT_ROOT/sites/all/modules/er/modules/
DOCUMENT_ROOT/sites/all/modules/er/er.module

8 Step 5: Enable ERcore in Drupal

At this point, the ERcore files and all prerequisites should be properly placed on the target. Here we install the ERcore modules within the Drupal framework. Do the following:
  • login to the target website as administrator
  • click Modules on the Drupal home page
  • scroll down to the EPSCOR section on this page
  • check EPSCoR Reporting
  • click Save configuration at the bottom of the page.
  • click Continue to the question about if to enable other modules.
  • if you get a question about “rebuild permissions” click Rebuild.
After several minutes, a status page should appear indicating if installation completed, partially completed, or failed. If installation seems to have completed partially, perform the following steps before trying more elaborate troubleshooting:
  • In the EPSCOR section of the Modules page, be sure that EPSCoR Reporting is checked. (This may occur if the Drupal entityreference module was not enabled prior to enabling ERcore. See Section .6.3↑) If EPSCoR Reporting is not checked, check it and click Save configuration again.
  • If this doesn’t work, try unchecking the flag, clicking Save configuration, followed by re-checking the flag and saving again.
  • In some situations “privilege violation” errors from the underlying file system are reported. If this occurs, you may need to modify the file attributes of all files copied to the target such that directories have “rx” protections for all users and regular files have “r” protection for all users. If this is too difficult with FileZilla, log into the target system and execute the following shell commands:
cd <target-modules>
find er -type d -exec chmod o+rx {} \;
find er -type f -exec chmod o+r {} \;
Note that the following errors are normal for a typical installation:
  • Error: No Institutions found!
  • Error: No Research Components found!
  • Warning: Taxonomy: <field> is extraneous.
The first two errors indicate initial site configuration data has not been entered yet. This data can be entered after ERcore installation is complete.

9 Step 6: Check installation status and troubleshoot

9.1 Basic installation status

At this point, ERcore should be installed properly. Check the following to be sure:
  • Go to http://<your-site>/admin/config/epscor/er/status to view the EPSCoR Reporting Status Report page.
  • Make sure there are no errors shown on this page other than those listed in the previous section. See Section 9.2↓ if abnormal errors are found on this page.
  • click Modules
  • scroll down to the EPSCOR section
  • make sure EPSCoR Reporting is checked
  • click Reports Recent log messages (or http://<your-site>/admin/reports/dblog)
  • this shows recent error log messages. look for anything unusual.
  • Note that there may be numerous errors from ERcore in the error log of the form “Unable to attach <xxx> to role <yyy>”. These error may be safely ignored if accompanied by a message of the form “Role <yyy> imported successfully”.

9.2 ERcore installation reset

In cases where installation has partially failed or some other internal error has been detected, the EPSCoR Reporting Status Report page can be used to reset individual ERcore components:
  • Go to http://<your-site>/admin/config/epscor/er/status to view the EPSCoR Reporting Status Report page.
  • The status of all ERcore components are listed on this page. If there are no errors or warnings, ERcore is installed correctly.
  • If an error is shown for an individual component, click reset to reinitialize that component to ERcore installation-time settings.
If errors are displayed for several similar components, they may be reset as a group as follows:
  • Click BULK RESET on the the EPSCoR Reporting Status Report page to display the available groups for reset: taxonomy, roles, bundles, flags, and rules.
  • Click the desired entry to reset all ERcore components in that group.
Continue resetting individual components or groups until there are no more errors on the EPSCoR Reporting Status Report page. Performing a Bulk Rest for all ERcore components is essentially the same as reinstalling ERcore.

9.3 Apache error log

If you want to be thorough, you can check the Apache error log:
  • click Reports Status report (or http://<your-site>/admin/reports/status)
  • click PHP (more information) (or http://<your-site>/admin/reports/status/php)
  • search for APACHE_LOG_DIR
  • this will be the directory where Apache error logs are kept
  • examine the log files in this directory for abnormal events

9.4 Clearing caches

Some problems with Drupal are fixed simply by logging out or flushing caches. This helps to insure that both client and server have identical data. Try any or all of the following:
  • logout and log back in to Drupal
  • close browser window on the client machine and start a new session
  • navigate to: ConfigurationDevelopmentPerformanceClear all caches

9.5 Double asterisk problem

On some installation, there is a “double asterisk” problem. Check your system for this anomaly as follows:
  • click Content ▷ Add Content ▷ Collaboration
  • scroll down to Collaborating Institution/Organization
If there are two red asterisks instead of one, then the following patch can be applied:
  • locate a file named DOCUMENT_ROOT/misc/states.js (see Section 3↑ about DOCUMENT_ROOT).
  • [TBA: enter instructions for editing states.js here.]
More information about the “double asterisk” problem, including a patch, can be found at:

9.6 MySQL server error

Some developers reported receiving PDO errors like "General error: 2006 MySQL server has gone away" which prohibited installation of ERcore. The problem was fixed by adjusting the max_allowed_packet size from 1M to 100M in the MySQL setup file, my.ini. More information about this problem can be found at:

9.7 Date and time error

After installation of the ER Core, if the following error "The value input for field is invalid:" appears on the Accomplishments page or the Home page, go to Configuration > Region and Language > Date and time and click on Save configuration. This should solve the value input error.

10 Step 7: Initial ERcore configuration

The menu options should be changed as follows:
  • click Modules.
  • scroll down to the Core section.
  • uncheck the Overlay module.
  • uncheck the Toolbar module.
  • scroll down to the Administration section.
  • check the Administration menu Toolbar style module.
  • click Save configuration at the bottom of the page.
  • logout and login again to see these changes.
In addition, modify these settings at Configuration ▷ Administration ▷ Administration menu:
  • check Adjust top margin
  • check Keep menu at top of page
  • check Cache menu in client-side browser
  • click Save configuration
To set basic site information, do the following:
  • click Configuration System Site information
  • enter value for site name (e.g.. “NH EPSCoR Reporting”)
  • optionally, enter value for site slogan (e.g. “Scratch site testing version of NH EPSCoR Reporting”)
  • verify system administration email address
  • specify the location of a front page if desired
  • click Save configuration
If you want to add a front page, the following example should get you started:
  • click Add content Basic page
  • enter a title (e.g., “Welcome to EPSCoR Reporting”)
  • enter a body for the page (e.g., the following html text):
<p>Five EPSCoR jurisdictions (Alaska, Hawaii, New Hampshire,
New Mexico, and Utah) self-organized to create a working
group designed to explore the creation of a common, web-based
data input/reporting output portal that would be suitable for
adoption across all EPSCoR jurisdictions and projects.
Following a series of conference calls and a voluntary
workshop at the New Mexico EPSCoR office with programmers,
PA’s, and PI’s, the coalition has determined that the Drupal
open source content management platform provides a powerful
tool for managing data inputs and reporting outputs via our
existing EPSCoR websites.</p>
<br/>
<img src="http://www.nmepscor.org/sites/all/images/5-juris-logos.jpg"
align="middle" alt="Five EPSCoR Jurisdictions">
  • for the above example, select Text format: Full HTML
  • under Publishing Options: check Published and Promoted to front page
  • click Save
It is recommended that the comments module be disabled.
  • click Modules.
  • scroll down to the Comments section under 'Core' (fifth from the top).
  • uncheck the Comment module.
  • click Save configuration at the bottom of the page.
User documentation and additional configuration pages can be found at:
  • EPSCoR Help Documentation
  • EPSCoR Admin Action EPSCoR Reporting Core Settings

11 Step 8: Drupal permissions configuration

Drupal permissions control which actions can be performed by a user and, additionally, which features are presented via menu selections and web page content. Perform the steps described in this section to insure proper operation of ERcore. Please note that ERcore documentation assumes permissions are set as described in this section and that deviation from these settings could create confusion to the readers of that documentation.

11.1 ERcore roles and permissions reset

The default Drupal permissions granted to the various user roles may vary from ERcore installation to installation. Begin permissions configuration by performing a Bulk Reset of the Roles bundle as follows:
  • Go to http://<your-site>/admin/config/epscor/er/status to view the EPSCoR Reporting Status Report page.
  • Print a copy of this page, either to hard copy or a file, for future reference. This step is especially important if your site is locally customized with special purpose roles and modules.
  • Click BULK RESET on the the EPSCoR Reporting Status Report page to display the available groups for reset.
  • Click Reset roles. Warning: if you have made customizations to your permissions, this will reset them.
This action resets permissions consistently across installations. For more information on Bulk reset, see Section 9.2↑.

11.2 Drupal permissions page

The Drupal permissions page is used by the site administrator to grant or deny permissions for user roles. Access the Drupal permission page using either of the following sequences:
  • Click People Permissions
  • Enter URL: http://<your-site>/admin/people/permissions
This page lists permissions granted to particular user roles available within ERcore. Available roles are listed across the top of the page with permissions granted for a particular role indicated with check marks below. Permissions are grouped by an alphabetized list of categories.

11.3 Reorder roles

The Drupal roles within ERcore should be appear in the following order:
  1. Anonymous user
  2. Authenticated user
  3. Administrator
  4. Administrative staff
  5. Faculty
  6. Student
  7. Guest
If the roles across the permissions page to not appear in this order, perform the following steps:
  • Click the Roles button while on the Drupal permissions page.
  • For each role that is out of order, drag the plus sign adjacent to the role up or down to adjust its order.
  • Click Save order to complete the ordering process.
When roles have been reordered, click Permissions to return to the permissions page.

11.4 ERcore permissions adjustment

This section lists permissions important to the operation of ERcore and provides appropriate settings for typical operation. There are two possible settings for a given permission and role:
  • Checkmark — permission is granted to users with this role.
  • no Checkmark — permission is denied to users with this role.
In the descriptions below, this selection is explicitly specified using the terms Grant and Deny, for checkmark and no checkmark, respectively. Compare the settings on your site’s permissions page with the settings described below and make appropriate changes to your site. Click Save permissions at the bottom of the permissions page when complete.

Administration menu

Permissions in this category generally concern the Administration Toolbar Menu or “black bar” menu at the top of most ERcore web pages. The following are important permission settings in this group.
  • Access administration menu settings — Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • Flush caches settings — Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff

EPSCoR Reporting

Permissions in this category control basic ERcore features. Set these as follows.
  • Administer EPSCoR Module:
    • Grant for Administrator only
  • Access EPSCoR Module Admin content:
    • Site preference for Administrator, either Grant or Deny
    • Grant for Administrative Staff
    • Deny for all other roles
  • Access EPSCoR Module content:
    • Grant for all roles
  • Access EPSCoR Module excel sheets:
    • Site preference for Administrator, either Grant or Deny
    • Grant for Administrative Staff
    • Deny for all other roles

Field Permissions

Permissions in this category control the level of access allowed to private fields within stored content:
  • Disabilities
  • Ethnicity
  • Gender
  • Phone (mobile)
  • Race
Field Permissions are listed in two groups within this section: general permissions first, and field-type-specific permissions second. The second group contains 5 specific permissions for each field-type, allowing various levels of access. Set permissions in this category as described below.
  • Administer field permissionsGrant for the following roles, Deny for all others:
    • Administrator
  • Access other users’ private fieldsGrant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
  • Create own value for field <field-type> — Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • Edit own value for field <field-type> — Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • Edit anyone’s value for field <field-type> — Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
  • View own value for field <field-type> — Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • View anyone’s value for field <field-type> — Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff

Filter

Permissions in this category control the types of explicit HTML markup that can be entered in webpage text. The following permissions should be changed:
  • Use the PHP code text format
    • Deny for all roles (for security reasons).

Node

Permissions in the Node category control the level of access allowed to various types of content, such as Institution or Publication. Node permissions are listed in two groups within this section: general permissions first, and content-type-specific permissions second. The second group contains 5 specific permissions for each content-type, allowing various levels of access. Set permissions in this category as described below.
  • Bypass content access control — Roles with this permission can create, edit, and delete any node, regardless of the individual “low-level” node settings. However, Add Content features are not presented consistently to users granted this permission. Set as follows:
    • Deny for all roles.
  • Access the content overview page — Roles with this permission have access to the /admin/content page and have a Content selection in the Administration Toolbar Menu. Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • <node-type>. Create new content — This node-type can be created. If granted, this node-type will appear on the Add Content page and the Add Content toolbar menu. Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • <node-type>. Edit own content — This node-type can be edited if the user created it. An edit button is displayed on the /admin/content page for content that can be edited. Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • <node-type>. Edit any content — This node-type can be edited regardless of which user created it. An edit button is displayed on the /admin/content page for content that can be edited. Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
  • <node-type>. Delete own content — This node-type can be deleted if the user created it. A delete button is displayed on the /admin/content page for content that can be deleted. Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student
  • <node-type>. Delete any content — This node-type can be deleted regardless of which user created it. A delete button is displayed on the /admin/content page for content that can be deleted. Grant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
Note that when the Bypass content access control permission is granted to a user, the Add Content selection in the Administration Menu will show that the user can create any node. However, the Add Content page at <yoursite>/node/add does not show entries for all nodes. As such, if this permission is granted, Add Content features are not presented consistently to users with that role.

System

The following permission in the System category controls availability of the the EPSCoR and Help menu selection in the Administration Toolbar Menu.
  • Use the administration pages and helpGrant for the following roles, Deny for all others:
    • Administrator
    • Administrative Staff
    • Faculty
    • Student

User

Permissions in this category control access to User Profiles. Set these as follows.
  • Administer users — Roles with this permission can change any user’s profile, and have a People selection in the Administration Toolbar Menu. Set as follows.
    • Grant for Administrator
    • Site preference for Administrative Staff, either Grant or Deny
    • Deny for all other roles

12 ERcore Update Process

This section describes the procedure for updating ERcore software. This process involves the following steps:
  1. Creating a test site for a trial installation.
  2. Updating the ERcore software on the test site.
  3. Data migration on the test site.
  4. If all goes well, update production site.
An important part of this procedure is data migration of the website content from the old version to the new version.

12.1 Create a test site

The first step in the ERcore update process is to create a fully functional working copy of the production website with the “old” version of ERcore. The following sub-steps are suggested to accomplish this.
  • Start with a test site with identical system and server software as the production site
  • Fully backup the test site, including the file system and SQL database.
  • Create a new SQL database on the test site.
  • Dump SQL database from production site into new database on test site.
  • Set permissions appropriately on all tables in new database.
  • Move or delete /var/www files from test system.
  • Copy /var/www directory tree from the production site to test site
  • Edit settings.php in the test site to use the new database.
At this point, the test site should contain a full working copy of the production site.

12.2 ERcore Update

With a production site “cloned”, the ERcore software update can be realistically tested on the test site. Many of the installation steps described in previous sections are still appropriate. These are listed below with differences noted. See appropriate sections above for details.
  • Step 1: Backup target site (Section 4↑) — Same as for initial installation but for test site.
  • Step 2: Check PHP.INI parameters (Section 5↑) — Same as for initial installation but for test site.
  • Step 3: Installing prerequisites (Section 6↑) — If prerequisites for the new version of ERcore are different than the old version of ERcore, install them on the test site at this time.
  • Step 4: Installing ERcore files (Section 7↑) — It is not necessary to “uncheck EPSCoR Reporting” on the Modules page. However, the <target-modules>/er/ directory tree contents should be deleted. Then, select and download the directory tree for the new version of ERcore onto the test system.
After the ERcore directory tree for the new version has been installed on the test system, perform the following steps to complete the ERcore update procedure:
  • login to ERcore on the test website as administrator
  • Go to http://<your-site>/admin/config/epscor/er/status to view the EPSCoR Reporting Status Report page.
  • Print a copy of this page, either to hard copy or a file, for future reference.
  • Inspect all outstanding (red) items and reset the necessary bundles (by clicking Reset this bundle). (Note that all bundles may be reset as a single step by expanding BULK RESET and clicking Reset bundles.)
  • Warning messages that include the text “Extra fields” indicate data migration issues from the old version to the new version. These are resolved in the next section.
  • If all items are successfully addressed (except for “Extra fields” items) then clear all caches. (See Section 9.4↑.)
  • Check the Drupal permissions for this new installation as described in Section 11↑. It is not advisable, however, to perform the Reset Roles action described in that section.
At this point, the new version of ERcore software should be installed properly on the test system and, except for “Extra fields” messages, the EPSCoR Reporting Status Report page should be free of errors. If any “Extra fields” messages are outstanding, perform the actions in Section 12.3↓, Data migration. Other wise, skip to Section 12.4↓, Production site update.

12.3 Data migration

For the current version, ERcore data migration is a manual process requiring intimate knowledge of Drupal, Drupal internals, SQL, and the implementation of ERcore features. While the process is relatively straightforward, it requires an appropriate knowledge of Drupal internals, thorough testing, and patience. This task should only should only be attempted by an experienced Drupal developer. An overview of the data migration process is given below.
“Extra fields” messages displayed on the EPSCoR Reporting Status Report page indicate that database formats used by the old version of ERcore have changed. Website content stored using the previous version of ERcore will need to be migrated to the data format used by the new version of ERcore.
At a conceptual level, the ERcore update process creates a new database schema for use by Drupal and ERcore. This new schema includes field and table definitions compatible with both versions of ERcore. In addition, database records in the updated installation are compatible with both versions of ERcore content. No data is lost during the update; database records from the previous version are retained and augmented to include new fields required for the new version of ERcore.
At a more detailed level, the following occurs while processing the EPSCoR Reporting Status Report page during ERcore software update (Section 12.2↑):
  • The existing database schema is compared against what the “new” ERcore software expects. If an “old” version of ERcore is detected, error messages are displayed for the affected fields.
  • Fields that are defined identically in both versions of ERcore will remain unchanged in the new schema and in the database records.
  • New fields (not used by the old version) are added to the schema. Database records will contain “empty” values for these new fields.
  • Old fields (not used by the new version) remain in the schema. Database records will contain the values previously stored by the old version of ERcore. These are labeled as “Extra fields” on the EPSCoR Reporting Status Report page.
  • Changed fields (same field name in both versions but different data definitions) are handled as two fields, an old and a new. The original field name is used with the data definition for the new version of ERcore; database records will contain “empty” values for these fields. A new field name is created for the data definition used in the old version; database records for these fields will contain the values previously stored by the old version of ERcore.
  • Details about new fields, old fields, and changed fields are provided in the messages displayed on the EPSCoR Reporting Status Report page.
Using the information displayed above, the task of data migration becomes one of manually transferring data values from old fields to new ones using the Drupal interface and SQL commands. This data migration should be performed on the test site with frequent backups and then thoroughly tested before attempting it on the production site.

12.4 Production site update

Once the above steps are performed, the new version of ERcore will be installed and all data migrated to the test system. Perform the following steps to finish the installation on the production site:
  • Fully backup the production site and set the site in Maintenance Mode.
  • Perform the steps listed in ERcore Update (Section 12.2↑) on the production site.
  • If required, perform the steps listed in Data migration (Section 12.3↑) on the production site.
  • Test the production site thoroughly and then remove it from Maintenance Mode.
For additional help with installing or updating ERcore, see contact information at the ERcore git repository main page: http://drupal.org/sandbox/shixish/1837936.