*Upgrade instructions*
Since ORSEE 3.1.0, there are two ways to upgrade ORSEE.
1) via fresh install, basic configuration, bootstrap data import from
old database, further configuration, refresher data import
2) via code upgrade, automatic database upgrade by dbupdates.php, and
post-upgrade configuration consolidation
Re 1) Fresh install path
- Install ORSEE according to the installation instructions,
INSTALL.howto.
- Configure your design, admin and public menu, participant profile
fields and form.
- Then you can fork:
-- either continue setting up details, or
-- import most setup data from your old system via "full bootstrap"
data import using Options/Prepare data import and
install/data_import/data_import_orsee3.php
- Finish configuration (e.g., rich text conversion) and test your
system.
- Once you are ready to go, in case you left your old production ORSEE
running in the meantime, you can do refresher data import via
"operational" data import.
Re 2) Code upgrade path
- Upgrade your ORSEE code to new version, either via git or by
downloading the zip and copying the new code over the old code.
- Compare settings-dist to your current settings.php and copy over
missing settings.
- Upon first access to admin part of the system, ORSEE will run an
automatic database upgrade. (Exception: MyISAM to InnoDB conversion in
ORSEE 3.4.0, see below.) It will record any upgrade results in
Statistics/Experimenter actions.
- Go through the configuration and edit, in particular for any new
features.
- I recommend to do this first on a copy of your system with a copy of
your database, to test the migration process.
- When everything worked well, you can then do the same process on
your production system: stop public site, do upgrade, restart public
site. You can copy over the style folder from your test install.
*Notes for upgrade from ORSEE ORSEE 3.0.0-3.3.0 to ORSEE >=3.4.0
ORSEE 3.4 comes with some fundamental new features which need some
attention when upgrading: full css-style, participant profile fields,
public and admin menu, richtext conversion, MyISAM to InnoDB
conversion. When you update via the code upgrade (path 2), most
displayed content will continue to work due to some backward
compatibility and fallbacks, but you want to configure them properly
as soon as you can.
Details:
1. ORSEE moved to a full css-based style.
- Each style in the style folder has 4 important files: orsee.css,
orsee_header.php, orsee_footer.php, colors.json. If any of them is
missing, ORSEE uses a default file instead.
- You can edit orsee_header.php and orsee_footer.php to change the
masthead etc., and orsee.css to change the design. You can set the
navigation orientation in Options/General settings.
- Colors can be set in the database in Options/Edit Colors and will be
taken over by css. To take over colors from your style's colors.json,
go to Options/Colors, and empty all the color text fields and click
"Change", and the colors will be refilled from the colors.json.
Otherwise, ORSEE default colors are used. Dark mode colors are
automatically derived from light mode colors.
2. Public menu and pages & Admin menu and pages
- ORSEE now let's you edit the menus displayed in the admin and public
area.
- You can also add new menu items tat are either outgoing links or
ORSEE pages. These pages now do not use HTML anymore but richtext (see
quick reference on richtext page, or ORSEE Wiki). A small set of HTML
tags is still supported for backward compatibility but I recommend
changing your content (mainpage, rules, privacy policy, imprint,
contact, etc.) to richtext formatting.
- Also check FAQ question and answer texts for html code which should
be converted to richtext, too.
3. Participant profile layout
- ORSEE now has a very flexible participant profile layouter. You can
add new profile fields of various types. You can configure them with a
wide range of settings. You can create variants of any field which
determine how the field is displayed at different places (public
create/edit pages, admin area) and for different sub-subjectpools.
- Any changes (except profile field deletions) are in "Draft" mode
initially and only take effect once you activate your current draft.
- Upon upgrade, your previous html-based template is still active
("Legacy participant profile form template"). After editing your new
profile form, switch participant profile rendering from "Legacy
template" to "Structured layout" in Options/General Settings.
4. MyISAM to InnoDB conversion
- From v3.4, ORSEE uses modern InnoDB tables which allow for for
transactions, low-level locking, etc.
- Your database will not be automatically upgraded, but you have to
run the script convert_orsee_to_innodb.sql via
% mysql orseedbname -uorseedbusername -porseeuserdbpassword <
convert_orsee_to_innodb.sql
- Especialy with large databases, this script might take a while. I
strongly recommend shutting down ORSEE during this time, via
Options/General Settings for the public area and
"$settings__stop_admin_site="y";" in config/settings.php for the admin
area.
*Notes for upgrade from ORSEE <=3.0.2 to ORSEE >=3.0.3* (ignore
otherwise)
With ORSEE 3.0.3 we fixed a bug in the database connection as well as
in the default install.sql file. This means that if you upgrade from
an ORSEE version before 3.0.3, there is a chance that some
non-standard characters (e.g. umlauts) are not correctly displayed
anymore. (So this problem should not affect any users who only use
English.)
If you import data from an older ORSEE version, double check whether
all imported fields (e.g. participant names with umlauts) are
correctly encoded.
If you experience this problem after an upgrade from older ORSEE
versions or after a data import, please run the script
"convert_orse302db_to_UTF8.php" in the install/ directory. This will
fix the wrongly encoded characters in your database such that they are
correctly displayed. Please do *not* run this script if your display
of nonstandard characters is ok.
*Notes for upgrade from ORSEE 2.x.x versions to an ORSEE 3.x.x
version* (ignore otherwise)
ORSEE 3.0.0 was a major new version, with many changes to the database
structure and to the code. For this reason, the procedure to upgrade
includes two simple steps:
- install the new version as described in INSTALL.howto and the ORSEE3
wiki
- import your previous data as described in the ORSEE3 wiki
As per the note above, check your imported data whether any umlauts
and other non-standard characters are displayed correctly.
