ORSEE3

This module can be enabled in Options/General settings. When enabled, it allows to receive and reply to emails within ORSEE, and to assign emails to experiments and participant profiles. This will create great transparency about any communication and dealings with subjects.

The email module retrieves emails from any POP3/IMAP account. This could be a university email account created for the lab, or a Google email account. (Some laboratories just create an alias email account at the university, e.g. foobarlab@foobbar.edu, and forward this to a Gmail account.) Typically, the email account would be the same as the one which is used as the sender address for all outgoing emails. (Otherwise, replies to those outgoing emails will not be received by the system.)

To set up the system, you will have to add the access details for the email account in the file config/settings.php (see section Installation for more instructions). You will have to specify the mail server type (pop3 or imap), the server name/address, the port (if not a standard port), the username to access the emails on this server, and the password for the email account.

The email is picked up by a regular task called retrieve emails, that needs to be enabled in Options/Regular tasks. Per default, it runs every 5 minutes. It will report the number of emails retrieved in the Regular tasks log (Statistics/Log files/Regular tasks), which is a good way to check that the setup works.

The email retrieval process can delete the emails on the server after retrieval, or leave them there. This can be configured in General settings. It is strongly recommended to delete messages after retrieval. Otherwise, whenever the check for new emails is run, the system will need to go through all emails on the server and check which have been retrieved yet and which haven't. This might be very resource-intensive, in the extreme it may take longer than 5 minutes, such that a new email retrieval job will interfere with the previous one that is still running.

A click on Emails in the navigation menu will show the Inbox with all emails that have not been marked as processed yet. Each row includes the subject line, the sender address, and date the message was received. Next to the date, a green dot in a circle (as opposed to an empty green circle) indicates whether this email has been read by somebody yet. A click on the dot can toggle the read/not read status of the email. If the email was assigned to a experimenters, a blue circle and dot next to the green one indicate whether one of the assigned experimenters has read the email yet or not. Lastly, a click on View message will open a popup that shows the email details.

Emails are shows as a “thread”, that includes the original received email, any replies sent by some experimenter, and internal notes added to the email. Every new retrieved email opens a new thread.

An email thread can be assigned to:

• an experiment, to a particular experiment session, or to a special mailbox;
• a participant profile;
• an experimenter (if this feature is enabled in Options/General settings).

The system will try to come up with suggestions for the experiment/session and participant field. The participant profile is guessed from the sender email address. If an experiment session was selected (and the data saved), then the drop-down list will include all participant profiles that are related to this experiment session.

The drop-down list for mailbox and session will include all sessions of currently unfinished experiments. If a participant was selected (and the data saved), it will also include all sessions the participant was/is enroled for, and all experiments the participant was/is eligible for.

If the feature is enabled, you can also assign an email to a particular administrator / experimenter. (See below for more details on ticketing.)

A click on the Save button stores these assignments in the database. From then on, this email will be listed in the email list of the respective participant profile (see section Editing participant profiles) as well as in email lists for sessions and experiments. The email list of a session is displayed below the participant list on the session participant list page (see Monitoring the enrolment process). The emails for an experiment can be accessed vie the button View emails for experiment on the experiment main page. The button will only appear if there is at least one email assigned to this experiment.

From the Inbox page you can also access emails in special mailboxes and in the trash. “Special Mailboxes” can be edited/created in Options/Mailboxes. A click on the link All mailboxes in the top left corner of the Inbox page will display a list of mailboxes, along with the number of email threads grouped by status. Emails assigned to experiments can be accessed as described above. Special mailboxes can be directly accessed from this list (not assigned is always defined as a special mailbox).

The Trash is another special mailbox. Whenever an email thread is deleted, it is first moved to the Trash, which can be accessed from the top left corner of the Inbox page or from the list of All mailboxes. When you open an email in the Trash you can undelete the email by clicking the respective button, which will move it back to the mailbox / experiment to which the email is assigned to. A click on Empty trash will delete all emails in the Trash permanently - this action is not reversible.

In the email popup you can also reply to the email or add a note. A click on Reply will open the reply form. (If the original email has multiple addressees or email addresses cc-ed, then there will also be a Reply all button that allows to reply and CC: all other email addresses.) Opening the reply form will automatically disable the assignment buttons. The form can be closed by clicking on the close icon on the top right of the reply form. To write the email, fill in the to:, cc:, subject and email body fields. All fields are pre-filled as in a typical email application. Click on Send email to submit the email. The email will also be saved to the database and show in the same email thread.

You can also add an internal note to the email thread that will only be visible to experimenters (for example, about some action you took in response to the email). A click on the Add notebutton will open a simple form with only one ext field for the note. (Similar to the reply form, opening the note form will automatically disable the assignment buttons at the top.) Click Add to add the note to the thread.

Setting the Processed switch to Yes (green) and clicking the Save button will remove the email thread from the Inbox. It will however still be listed in any email list related to a participant, experiment, session, or special mailbox.

The email module has a very detailed user privilege structure that allows for different procedures to deal with emails. A user (type) can have the privilege to

• read an email,
• change the assignments,
• reply to the email,
• add a note to the email thread, or
• delete the email

at any of the following levels

• all emails,
• all emails assigned to an experiment for which the user is listed as experimenter,
• all emails assigned to this user.

When the software checks the access level, it first looks up whether the user can access all emails. If that is not the case, the software checks whether the user is allowed to access emails which are assigned to experiments for which she is listed as an experimenter, and if so it will check whether the email is indeed assigned to an experiment of this user. Finally, if this check fails, the software will check whether assignment to specific users is enabled, and whether the email had been assigned to this user. If all checks fail, the respective function (read, change, reply, note, delete) will not be made available to the user.

In addition, there are privileges to add, edit, and delete special mailboxes, and to view and empty the trash, which are usually reserved for administrator roles. All privileges for all user types can be edited in Options/Admin types.

To give some example setups, consider the following use case: A laboratory wants to allow administrators to edit all emails, but experimenters should only be able to see, change, and reply to emails that are assigned to their own experiment. (this implies that some administrator has to monitor incoming emails and assign them to experiments/sessions).

This can be achieved by the following setup: In Options/General settings, set Email module: Allow to assign emails to experimenters? to No. Then assign the following privileges to the experimenter role.

Note that the values in the last column actually don't play a role, since assignment to experiments is disabled. For admin types, all privileges can be set to 'Y'.

Another policy might be to allow all users to read emails, but to assign emails to specific experimenters for processing and replying (like in a ticketing system. (And whether the email is assigned to a particular experiment should not play a role.) A privileges setup for experimenters which achieves this would be:

The flexible privilege setup also allows for more extreme cases (in the one extreme, all users could be eligible to read, change, answer any email; in the other extreme all these rights could be exclusively assigned to an admin role), as well as many mixed setups.