- System overview
- The participant view
- The experimenter view
- Maintaining the subject pool
- Other experimenter interface features
- Online configuration
- Tips and tricks
You find the general options page in the section Option/General settings. It should be sufficient if you edit these settings once - when you install or upgrade the software. Beware that all of these settings have an impact on the system's functions and appearance.
Most settings are pretty self-explanatory. The following list contains further information only one some items:
Administrator Standard Language: Choose here the standard language for the administration area. Registered admin users might choose their own language in their user profile (from the list of installed languages).
Public Standard Language: The public standard language is the language which will be used for the public pages when visitors and subjects browse to your site. The public standard language must be made available on public pages and as participant language (see section Edit basic language settings).
System support email address: Fill in here the email-address for your system. This address will be used as the sender address for all emails sent by the system (except if overridden for a particular experiment, see next option) and as contact/support address. Thus, make sure this is a valid email address and you have access to the account.
Allow experimenters to change the sender email address for their experiments?: If this is enabled, experimenters can enter a different sender address for emails related to their experiment on the experiment creation page. If you want al emails from the recruitment system coming from your support email address, then disable this.
Type of sending emails: On web servers which have no DNS entry, i.e. are only known by their IP address, the original PHP mail function (our
directmethod her) sometimes does not work because it does not set a valid so-called 'envelope sender address'. When this problem arises, you can ask ORSEE to try to directly use the sendmail function of your system (here called
indirect, note that this can only work on unix/linux systems). So, first try to send emails with this option set to 'direct'. If that does not work, try 'indirect'.
If indirect: path to sendmail program/wrapper?: When using the
indirecttype of email sending (see above), we need the path to the sendmail program/wrapper on your system. On Linux servers the program is usually located in
/usr/sbin/sendmail. If not, you may find out with the command
Number of emails sent from mail queue on each processing: ORSEE's internal mail queue is processed regularly by a regular system task. Fill in here the number of e-mails which should be sent on each processing. See also the sections on Regular tasks and Mail queue.
Bcc all outgoing emails to an email address?: Enabling this option allows you to blind-carbon-copy an email address on any outgoing email communication. This may be used for monitoring purposes, for example you could have a Gmail account as a catch-all for all communication, which you cans search when needed.
Address which to bcc: The address which should be bcc-ed. Multiple addresses can be added by separating them by commas.
Enable module to receive emails within ORSEE?: Whether you want to enable the email module. See section Email module.
Email module: Delete emails from server after retrieval (strong recommendaion: yes)?: See section Email module.
Email module: Allow to assign emails to experimenters?: See section Email module.
Stop public site: If you set this to 'yes' then visitors of the public/subject area of ORSEE will be redirected to an error page stating that the system is currently maintained. However, when you are logged in as an administrator you are still allowed to visit the subject area. Thus, this feature might be useful when you are working on the database or are installing/upgrading.
Style for Public Area: Choose here the style for the publicly accessible pages of your ORSEE installation. The list of styles is taken from the
/stylesdirectory. See section Styles on how to install and edit a style.
Style for Administration Area: Select the style which should be used in the administration area.
First part of each page's title tag?: This is the first part in the title tag of each html page of the system. For example, if it is set to 'ORSEE', then the title for the options main page is 'ORSEE: options', which will appear on browser title and tabs on the user's computer.
Participant calendar: Hide public experiment name?: In the public calendar, you might want to hide the public experiment name. For example, you might fear that your subjects talk to each other about their experience in a specific experiment. When hiding the experiment name (and simultaneously choosing just one background color for all experiments, see section Colors), participants cannot learn from the calendar whether they participate in the same experiment or in different ones.
Include “sign up until …in session list in invitation email?
: This setting determines whether the enrollment deadline is listed along each session date in the session lists included in experiment invitation emails. *Include “sign up until …
in session list on enrolment webpage?: The same, but for the actual enrollment webpage. If you don't want enrollment deadlines included, set to
Include weekday in session date whereever displayed?: If enabled, this will include the weekday in the session date, wherever it is displayed.
Enable ethics approval module?:
Enable payment tracking module?:
Enable the “rules” checkbox in participant profiles and session participant lists?: If you want to track whether participants have signed the lab rules, enable this feature here. The idea behind this is a lab policy that requires subjects to personally sign a copy of the laboratory rules, and to track these signatures in participants list.
Allow to add participant numbers to non-ORSEE-experimental laboratory bookings?: Whether it is possible to add participant numbers to events created in the calendar, for example for experiments that take place in the lab but are not organized with ORSEE. See also section Calendar and events.
Default registration subject pool?: Select here the default subject pool out of your configured sub-subjectpools. (This is merely a catch-all and will usually not be needed. Typically, when more than one subjectpool is configured then the subject self-selects, and if only one subjectpool is configured then that is automatically applied. See also section Sub-subjectpools.
Do subjects have to accept the lab rules when enroling?and
no, then the rules acceptance page in the registration process will not be shown at all.
Eligible assigned subjects can only enrol after having received an invitation email?: This setting determines whether subjects are able to enroll for
livesessions as soon as they are made eligible for the experiment (this was the standard in ORSEE<3.0) or whether they should only be able to enroll once an invitation email has been sent to them.
Enable special enrolment page for mobile devices?: Whether, when subjects access the session enrollment page from their mobile device, they should be redirected to a mobile version of the enrollment page (
yes) or should receive the standard page (
Allow experimenters to add public note to experiments (displayed on participant enrolment page)?: See section Creating an experiment.
Allow experimenters to add public note to sessions (displayed on participant enrolment page)?: See section Creating sessions.
Allow experimenters to customize session reminder emails for their experiments?and
Allow experimenters to customize enrolment confirmation emails for their experiments?: See section Inviting participants.
Allow experimenters to apply “permanent queries” to new subject pool members?and
When new subjects are assigned through a permanent query, also send an invitation email?: See section Permanent queries.
Allow subjects to cancel their session enrolment?: By setting this to
yesyou are allowing subjects to cancel their session enrollment themselves.
If yes: Allow cancellation until how many hours before session start?: This will be the deadline (in hours before the session) until when the subject can cancel her session enrollment.
If yes: Participation status to be assigned to subjects who canceled their session enrollment: The participation status to which the subject is set after cancellation. Basically you have two options: 1) You could choose
Not set. This implies that the subject is “thrown back into the pool” and are able to enroll for other sessions of the same experiment (or even the same session). 2) You create a participation state
self-cancelledand select that here. This implies that the subject will not be able to enroll in other sessions of the same experiment.
Send warning email on no-show?: State here whether warning emails should be sent to subjects who did not show up at an experimental session. To make that work you will also have to enable the corresponding regular task (see section Regular tasks). The email template can be edited in Options/Email templates.
Exclusion Policy: Max. Number of No-Shows: This is the threshold of no-shows after which a subject is excluded from further experiment participations. The number stated here used in warning emails and and when testing for automated exclusion (see also Reputation system).
Automatically exclude participants after max no-shows?: State here whether participants should be automatically excluded once they reached the no-show threshold above. You have to enable the corresponding regular task for this (see section Regular tasks).
Participant status to be assigned to excluded subjects: Choose the participant status to which an excluded participant should be assigned to. See also section Participant states.
Inform excluded participants about automatic exclusion?: If participants who are excluded due to the automated reputation system should be informed by an email about their exclusion, choose
yeshere. The email template can be edited in Options/Email templates.
Restrict calculation of no-shows to sessions after a certain date?and
If yes, use this date: The above options allow to deal with no-shows: you can send automatic warning emails, and automatically exclude participants from further participation if their no-show count reaches a certain threshold. However, when changing your rules or migrating to a new rule, you may want to count no-shows only from a specific date on. These to settings allow you to enable and set a first date from which on no-shows will be counted.
Allow restriction of experiment page access to experimenters?: ORSEE allows that experiment owners can restrict the access to experiment-relevant pages to experiment owners. Only users who have the corresponding user right (e.g. system administrators) may override this. You may enable or disable the possibility to restrict experiment access here.
If restriction enabled: Should a new experiment be restricted by default?: Per default, access is unrestricted to allow for free exchange. However, as a lab policy you can change this default for new experiments to
restricted(which then can be overridden by the experimenter).
Regular expression for admin passwords: In this field, enter the perl regular expression that should be applied as a password strength check to users passwords. Remember that users can access a lot of data, so their passwords should be sufficiently strong. A description of the syntax can be found here: http://php.net/manual/en/reference.pcre.pattern.syntax.php
Require new password to be different from old password?: If set to
yes, then whenever a user changes her password the new password must be different from the old password.
Maximum number of failed admin logins before admin account is locked?and
Number of minutes to lock account until another login attempt is allowed?: This is a security feature protecting against brute-force-attacks on the admin user login (which try out many possible passwords). After a number of failed logins an account will be locked for a number of minutes before a new login attempt can be tried.
Disable auto-submit on admin login form?: In some internet browsers that offer an autofill feature for user names and passwords, the form is automatically submitted. This may interfere with ORSEE's convenience feature of automatic submission the form once the password is entered. In particular when the password is wrong, this may result in repeated automatic submission of the wrong password and in deactivation of the user's ORSEE account. This setting allows to disable the auto-submit feature in the login form in ORSEE.
How should subjects authenticate with the system?: Please see section Subject authentication for a detailed description of this setting.
Regular expression for participant passwords: If the subject authentication is set to
email address and password(or to
migration), then subjects will need to choose a password upon registration with the system. This regular expression is applied as a password strength check to users passwords. A description of the syntax can be found here: http://php.net/manual/en/reference.pcre.pattern.syntax.php
Maximum number of failed participant logins before profile is locked?and
Number of minutes to lock participant account until another login attempt is allowed?: This is a security feature protecting against brute-force-attacks on the participant account (which try out many possible passwords). After a number of failed logins an account will be locked for a number of minutes before a new login attempt can be tried.
Path to server log file (access.log)?: To deliver web usage statistics for your ORSEE system, we need the path to your webserver's access_log file. The file properties need to be set such that the file is readable for the user account your cron job for regular tasks is running under (the PHP code of ORSEE is executed by the cron job, and that code executes the
webalizerprogram which in turn reads the
access_logfile). If in doubt, ask your web server administrator.
Upload max size in bytes?: Enter the maximum allowed size for uploaded files, in bytes (so a MB is 1048576 (=1024*1014) Byte). Note that the file size might be further restricted by your local webserver and PHP configuration.
Emailed PDF Calendar: Number of months included?: Choose the number of months (current plus future months) which should be included in the calendar that is regularly sent out by e-mail to subscribed administrators.
When exporting ORSEE calendar: How many months should we go back?and
… into the future: When the ORSEE calendar is exported for import in other calendar applications, the system produces a file with events. The question is which events should be included. You define this here by choosing which calendar months should be exported, from a certain number of moths before the current date until a certain date in the future.
On the page Options/Default Values you may configure all values preselected in item creation forms and other settings. In particular, these are the following:
Default administrator type?: The type which should be selected by default when a new ORSEE user profile is created.
Log files: entries per page?: The number of rows shown on each page of log files entries.
Participant statistics: How many months should we go back when tracking over time?: For statistics per month, the table and figure needs to be restricted to a specific number of months. For example, choosing a 12 here means that monthly statistics will cover the last year.
Recruitment report: Maximum number of rows per report table: In the ORSEE recruitment report, we may want to restrict reported frequencies (in subject pool statistics etc.) to the X most common ones. Choose X here.
PDF Calendar: title font size?: The font size of the title in the PDF version of the experiment calendar.
PDF Calendar: table entry font size?: The font size of the calendar entries in the PDF version of the experiment calendar.
PDF Participant list: title font size?: The font size of the title in the PDF versions of participant lists.
PDF Participant list: table entry font size?: The font size of the row text in the PDF versions of participant lists.
Multipicker list of experimenters: max number of columns?
Participant query: Multipicker list of experiment classes: number of columns?
Participant query: Multipicker list of other experiments: number of columns?
Participant query: default size of random subset?: For the random recruitment ORSEE selects only a subset of participants. Fill in here the default size of the subset shown in the query form.
Participant query: Number of saved queries to show in query form when …: The query tool used in participant searches and for assignment of subjects to experiments allows to load previously saved queries. State here how many recent queries the
Load saved querydropdown should include, for query tools displayed when searching for active participants, searching for all participants, assigning new participants, and de-assigning participants.
Laboratory: opening time?: State the opening time of your laboratories, i.e. the time when the first experiment may start. This value and the next one are mainly used to divide non-experimental lab bookings that span several days into day chunks.
Laboratory: closing time?: When should the last experiment be finished each day?
Laboratory: max number of participants?: How many participants fit in your biggest laboratory?
Laboratory/Experiment Session: default number of participants?: State here the default number of participants for an experimental session to be used on the session creation page.
Experiment session: max number of reserve participants?: What is the maximal number of reserve participants to be invited for an experimental session?
Experiment Session: default number of reserve participants?: What is the default number of reserve participants?
Experiment Session: max duration in hours?: What is the maximum time an experimental session should last?
Experiment Session: duration minute steps?: For session duration: which minute steps should be allowed in the form?
Experiment session: default duration?: What is the default session duration time?
Experiment Session: registration end: max hours before session?: State here the maximum number of hours before the session when the registration period should end.
Experiment Session: registration end: steps for hours before session?: In which steps the number of hours for registration period end should be shown on the session edit page?
Experiment Session: registration end: default hours before session?: Fill in here the default end time of the registration period (in hours before session).
Experiment Session: default for “send session reminder on”-condition?: What should be the default rule applied to a session when checking if the session reminders should be sent out. For an explanation of these rules please refer to section Creating sessions.
Experiment Session: send session reminder email: max hours before session?: State here the maximum number of hours before the session starts at which the session reminder email should be sent.
Experiment Session: send session reminder email: steps for hours before session?: In which steps the number of hours for the session reminder should be shown on the session edit page?
Experiment Session: send session reminder email: default hours before session?: Fill in here the default time for sending session reminders (in hours before session).
Experiment Session: “session start”-field: years backward?: On the session creation page you have to specify the time of the session, including the year. Since we cannot show all years since 0 B.C., state here the number of years the list should go backward from the current year.
Experiment Session: “session start”-field: years forward?: State here the number of years the list should go forward from now.
General mail queue display: number of entries per page: How many emails should be shown per page when browsing the general mail queue? See also section Mail queue.
Experiment mail queue display: number of entries per page: How many emails should be shown per page when browsing an experiment-specific mail queue?
You can choose most colors used in the system with the online tool provided in Options/Colors. On the top left of the page you can choose the ORSEE style (see also Styles) for which you want to edit colors, go there by clicking
The colors are grouped and contain some meaningful names. To change a color, either edit the text (colors are given in hexadecimal code), or click on the small color field. The latter will open a small popup where you can choose the color. A click on the
OK button in the popup will transfer the chosen color code to the text field.
The fields for
calendar_event_reservation are different, they expect lists of colors, separated by commas. You can use hex-codes here as int he other fields, or color names (see for example here: http://www.w3schools.com/html/html_colornames.asp). When displaying sessions in the ORSEE public calendar, the system will take the color list in
calendar_public_experiment_sessions and assign them to different experiments, rotating through if there are more experiments than colors in the list. The same procedure is applied for experiments in the admin calendar (
calendar_public_experiment_sessions) and for events in both calendars (
calendar_event_reservation). If you want all experiments/events to be displayed in the same color, simply specify only one color in the list.
The colors that will have the biggest effect on the overall design of the page are the ones listed in the subsections
Colors for header,
Color to be used in <body> tag of html page, and
Colors for any kind of lists.
The regular tasks are tools to process functions of the system not initiated by a user action. To set them up you have to configure a cron job as described in the wiki section on installation of regular tasks (cron).
Regular tasks can be configured by browsing to Options/Regular tasks. First, you will see a list of regular tasks available for the system with information about their regular due-date and the time of their last execution. You may run a regular task immediately by clicking the 'Run now' button in the respective row.
A click on the
Edit link in a row lets you enable/disable a task and change its schedule.
The following tasks are available:
apply_permanent_queries: This process will check whether there are any subjects who have recently registered with the recruitment system. If that is the case, the tasks checks whether there are any current experiments that have active permanent queries. If so, the permanent queries are one-by-one (in the order of their activation date) applied to the set of new participants. If a participant matches a query, he will be made eligible for the experiment and (if this setting is enabled in Options/General settings) will receive an invitation email to the experiment.
check_for_noshow_warnings: Checks if participants did show up at experimental sessions (that are marked as
balanced) and sends a warning e-mail to the participants who did not show up, telling them that they will be excluded after a certain number of no-shows. This is also configurable in General settings.
check_for_participant_exclusions: Checks whether participants did not show up a certain number of times, excludes them from further experiment participations, and sends a notification message to the participant. This is also configurable in General settings.
check_for_registration_end: When the enrolment period for an experimental session has expired, this function will send out a notification e-mail to the experimenters of the experiment with information about the current state of enrolments for the session. The registration deadline is configurable on the session creation page (see Creating sessions).
check_for_session_reminders: At the time specified in the session properties, a reminder email will be sent to subjects registered for this session. The sending of the reminder is based on a rule set at the session creation page (see Creating sessions).
process_mail_queue: Sends the next batch of invitation, bulk and reminder emails from the ORSEE mail queue. The number which should be send each time is configurable in General settings. If this task is not enabled, no invitation emails will be sent from the system. See section Mail queue for more information.
retrieve_emails: If the email module is enabled in Options/General settings, then this process (if enabled) will retrieve emails from the email account specified in the main configuration file (see also sections The main configuration file and Email module).
run_webalizer: Runs the program 'webalizer' on the system's web server
access_logfile and dumps the output to the
/usage/folder of the ORSEE installation. The results can then be accessed via “Statistics/Server usage statistics”. Please consult section Web server statistics and General settings for information on installation and configuration.
send_experiment_calendar: Sends an e-mail with the experiment calendar for the current month as PDF file to all experimenters who subscribed. The template for this email can be edited in Options/Email templates.
send_participant_statistics: Sends an e-mail with current subject pool statistics to all experimenters who subscribed. The template for this email can be edited in Options/Email templates.
update_participants_history: Summary statistics of participants'
number of experiment registrationsand
no-showsare computed in the background by a regular system task rather than being calculated on-the-fly every time they are needed. You must enable this regular task to allow the reputation system to work properly, see also section Reputation system.
ORSEE comes with a sophisticated user rights management. The users of the administration area can be assigned to different 'Admin types' on their profile page (see section User management below). For each type, the user who has the right to change the administrator types (normally the system administrator) can specify the functions which users of this type are allowed to access. Some of these user privileges are organised hierarchically, such that that some privileges may require other privileges to be granted before.
To configure the administrator types, browse to Options/User types and privileges. You will see a list of administrator types with their respective rights. By clicking on the 'Edit' link next to a type you may change the rights of that type. Use the 'Create new' button to add a new administrator type.
On the configuration page for an administrator type, you see long list of all available rights of the system. The second column of each row shows the name of the right, the third column provides a short description, and the forth column lists necessary precondition rights for the right concerned. The small checkbox in first column of a row indicates whether the right is enabled for this administrator type or not. You may change the assigned rights by checking and unchecking the boxes. By clicking the 'Change' button at the bottom of the page you save your changes. Use the 'Delete' button to delete the type.
Note: The use of experiment access restrictions (see section Creating an experiment) may overlap with these user rights. That is, for a user to access a function for a particular experiment, (1) this function must be allowed for the user's administrator type, and (2) the user must have the right to access the particular experiment (if his right to override experiment restrictions is not enabled).
The default types delivered with ORSEE are listed below. These types are organized in a hierarchical fashion, i.e. every type has all rights of the former types. However, overlapping type organizations are feasible, too.
nobody: This type is not even allowed to login into the administration area. Use it for example for users who should only receive calendar and subject pool statistics from the system.
visitor: A 'visitor' is allowed to login and to see experiment, session and participant data and statistics. However, she is not allowed to change any data in the system.
showup_updater: Some laboratories use student assistants to update the participation data for conducted experimental sessions. This user type is allowed to edit the participant lists for experimental sessions and to upload files for experiments.
experimenter: For the 'experimenter' type all functions which are needed to organize an experiment in a completely configured system are enabled.
admin: This type is thought for system administrators. It allows for adding and editing users (and their type), to override experiment restrictions, delete experiments and non-empty sessions, edit language phrases, regular tasks, and to edit the most options of the system.
installer: For the installer all functions which normally are only needed when setting up or upgrading the system are enabled. These include language installation, data import, editing general options and default values, and adding/deleting of most option items.
developer: The 'developer' has access to all functions of the system. The extra rights compared to the 'installer' are only functions which may be needed when developing the system, i.e. when changing the code. In the user right list these functions are highlighted with 'dev!', and they are usually not of any use for running the recruitment system.
Note that these are just the default types shipped with the software. You can freely edit these types, or create new types.
Users of the administration area of ORSEE can be edited in Options/User management. You see a list of registered users, with
enabled accounts listed first. In this list you can quickly change some basic settings for users: their type, whether they are an experimenter or not (see also below), and whether their account is enabled or disabled. A click on
Save changes in list will store the changes made in the table rows to the database.
On the edit page for a user, the administrator sees the same form as the users in their profile area (see section My profile), but possible with some additional items (depending on the administrator privileges):
Username: The login name of the user. CaSE and spaces matter.
Type: The user's administrator type. For details, see section User types and privileges above.
Account: You can
disablethe user account. When the account is
disabled, the user cannot log into the system. This provides an easy way to disable an account when a researcher is not active anymore, without having to change the user type or the password etc. It also allows to quickly re-enable the account if the user returns.
Is experimenter?: When this option is enabled, the current user is included whenever an experimenter selection form field is shown (e.g. on experiment, session, and event creation pages, or in the query tool). When the option is disabled, the user is not included in such fields, so you should disable this only for users who will never run an experiment themselves (computer support, administration).
Request password update: If this is set to
yes, then the next time the user logs into the system she will be required to change her password (with password strength tests applied), and cannot access any other functions until she has done so.
Password: You may change the password of the user here. This field is only processed if non-empty. Note that here, for administrators, the password strength rules defined in Options/General settings will NOT be applied. This allows the administrators to create an account with a default password that the user changes with the next login.
The page also provides some information about the last login (attempt) of the user, how many failed logins there were since the last login, and whether the account is currently locked. If the account is locked, the administrator can unlock it manually here.
You may delete a user using the
Delete button. However, it is strongly recommended to not delete an administrator account, and instead simply disabling the account (see above). This keep the user's information and its connections to experiments in the system.
Traditionally, ORSEE authenticates subjects via a unique token in the URL they use to access the system. The individualized URL serves as a key, and should be treated like a password. The advantage of this procedure is that the link can be included in any email to the subject, the subject cannot forget a password, the profile page and session enrollment page can be easily bookmarked, and subject passwords do not need to be handled and stored in the database. Usually, the information collected in ORSEE installations is of little value to outsiders (names and email addresses).
However, from version 3.0 on, ORSEE also allows for subject authentication using username and password. The email address of a user will serve as the username, the password can be freely chosen subject to a password strength requirement (defined in Options/General settings). For ORSEE users who used the
token-method before and want to use
username/password authentication in the future, the system also provides a
Specifically, in Options/General settings you can set the subject authentication method to one of three values:
Per URL token: Any email from the system includes a personalized link to the participant's profile page and session enrollment page. The link is personalized with the use of a unique token. Using this token that is transmitted in the URL the system can identify the subjects and display the personalized page. Subjects are asked to keep their URLs confidential (like a password) to protect their own data.
Migration: From URL token to username/password: When this method is enabled, then subjects can still authenticate with their token. However, they are immediately redirected to a page that asks them to choose a password. Once a subject has chosen a password, it cannot authenticate anymore using the token method, and will have to provide email address and password to log into her profile or enrollment page (as described below).
Email address and password: When a subject creates her account with the system, she will be asked to choose a password. Whenever she accesses a personalized page of the system (participant profile or session enrollment page), she will be asked to authenticate herself using her email address and her password. There are two new options: the subject can change her password any time, and she can request a password reset when she has forgotten her password. For the latter, she first has to provide the email address that is stored in her account. She will then receive an email with a link and unique token that allows her to choose a new password (the validity of the token will time out after one hour).
Important note: If you are planning to migrate from a
URL token system to a
username/password authentication system, you will have to make sure that all email addresses are unique in the database. The
URL token system can tolerate duplicates in email addresses. But in the
username/password authentication system, the email address is used as the username, and therefore has to be unique. So before you start the migration, do a thorough search for duplicates in email addresses, and change the email addresses of (inactive) profiles such that email addresses are truly unique in the system. (the uniqueness requirement also extends to inactive profiles.)