From c84ab8d65dec5b3ceca052c4039c214382086d31 Mon Sep 17 00:00:00 2001 From: kristian Date: Tue, 4 Jun 2024 10:38:13 +0200 Subject: [PATCH] Set 3.9.x as default docs in versioning --- docusaurus.config.js | 9 +- .../Group_studies/Example-Group-Studies.md | 28 + .../Write-Group-Studies-I-Setup.md | 55 + ...oup-Studies-II-JavaScript-and-Messaging.md | 66 + .../Group_studies/_category_.json | 4 + .../Manage_your_JATOS/Administration.md | 32 + .../Customize-JATOS-Home-Page.md | 56 + .../Manage_your_JATOS/Troubleshooting.md | 44 + .../Manage_your_JATOS/Update-JATOS.md | 132 + .../Manage_your_JATOS/User-Manager.md | 75 + .../Manage_your_JATOS/_category_.json | 4 + .../version-3.9.1/Overview/Contact-us.md | 40 + .../Overview/Data-Privacy-and-Ethics.md | 94 + .../version-3.9.1/Overview/Get-started.md | 41 + .../version-3.9.1/Overview/Installation.md | 48 + .../Overview/JATOS-Tryout-Server.md | 15 + .../Overview/Papers-Citing-JATOS.md | 483 ++++ .../Run-an-experiment-with-JATOS-Workflow.md | 44 + .../version-3.9.1/Overview/Whats-JATOS.md | 35 + .../version-3.9.1/Overview/_category_.json | 4 + .../JATOS-API.md | 260 ++ .../JATOS-Results-Archive-JRZIP.md | 282 ++ .../JATOS-Study-Archive-JZIP.md | 277 ++ .../JATOS_Configuration.md | 1052 ++++++++ .../_category_.json | 4 + .../jatos.js-Reference.md | 2303 +++++++++++++++++ .../Connect-to-Mechanical-Turk.md | 65 + ...ross-sectional-and-longitudinal-studies.md | 98 + .../Deploy-to-a-server-installation.md | 23 + .../End-page-after-your-study-finished.md | 54 + .../Run_your_study/Manage-Results.md | 133 + .../Run_your_study/Restricting-study-flow.md | 63 + .../Run-your-Study-with-Study-Links.md | 158 ++ .../version-3.9.1/Run_your_study/Study-Log.md | 23 + .../Run_your_study/Tips-and-Tricks.md | 90 + .../Run_your_study/Use-Prolific.md | 62 + .../Run_your_study/Worker-Types.md | 66 + .../Run_your_study/_category_.json | 4 + .../Bring-your-JATOS-online.md | 37 + .../Expose-your-local-JATOS.md | 63 + .../Install-JATOS-via-Docker.md | 143 + .../JATOS-in-Amazons-Cloud-without-Docker.md | 19 + .../JATOS-in-a-cluster.md | 232 ++ .../JATOS-on-DigitalOcean.md | 190 ++ .../Serving_the_Internet/JATOS-on-a-server.md | 213 ++ .../Serving_the_Internet/JATOS-with-Apache.md | 61 + .../JATOS-with-Docker-Compose.md | 123 + .../Serving_the_Internet/JATOS-with-MySQL.md | 192 ++ .../Serving_the_Internet/JATOS-with-Nginx.md | 113 + .../Serving_the_Internet/_category_.json | 4 + ...apt-pre-written-code-to-run-it-in-JATOS.md | 112 + .../Write_your_study/Change-studys-members.md | 22 + ...ombine_two_pre_written_studies_into_one.md | 61 + .../Write_your_study/Create-a-new-study.md | 33 + .../Write_your_study/OSWeb-and-JATOS.md | 22 + .../Session-Data-Three-Types.md | 58 + .../Submit-and-upload-data-to-the-server.md | 26 + .../Write-your-own-Study-Basics-and-Beyond.md | 118 + .../Write_your_study/_category_.json | 4 + .../Write_your_study/jsPsych-and-JATOS.md | 47 + .../Write_your_study/labjs-and-JATOS.md | 20 + .../version-3.9.1-sidebars.json | 8 + versions.json | 1 + 63 files changed, 8246 insertions(+), 2 deletions(-) create mode 100644 versioned_docs/version-3.9.1/Group_studies/Example-Group-Studies.md create mode 100644 versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-I-Setup.md create mode 100644 versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-II-JavaScript-and-Messaging.md create mode 100644 versioned_docs/version-3.9.1/Group_studies/_category_.json create mode 100644 versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md create mode 100644 versioned_docs/version-3.9.1/Manage_your_JATOS/Customize-JATOS-Home-Page.md create mode 100644 versioned_docs/version-3.9.1/Manage_your_JATOS/Troubleshooting.md create mode 100644 versioned_docs/version-3.9.1/Manage_your_JATOS/Update-JATOS.md create mode 100644 versioned_docs/version-3.9.1/Manage_your_JATOS/User-Manager.md create mode 100644 versioned_docs/version-3.9.1/Manage_your_JATOS/_category_.json create mode 100644 versioned_docs/version-3.9.1/Overview/Contact-us.md create mode 100644 versioned_docs/version-3.9.1/Overview/Data-Privacy-and-Ethics.md create mode 100644 versioned_docs/version-3.9.1/Overview/Get-started.md create mode 100644 versioned_docs/version-3.9.1/Overview/Installation.md create mode 100644 versioned_docs/version-3.9.1/Overview/JATOS-Tryout-Server.md create mode 100644 versioned_docs/version-3.9.1/Overview/Papers-Citing-JATOS.md create mode 100644 versioned_docs/version-3.9.1/Overview/Run-an-experiment-with-JATOS-Workflow.md create mode 100644 versioned_docs/version-3.9.1/Overview/Whats-JATOS.md create mode 100644 versioned_docs/version-3.9.1/Overview/_category_.json create mode 100644 versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-API.md create mode 100644 versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Results-Archive-JRZIP.md create mode 100644 versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Study-Archive-JZIP.md create mode 100644 versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS_Configuration.md create mode 100644 versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/_category_.json create mode 100644 versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/jatos.js-Reference.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Connect-to-Mechanical-Turk.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Cross-sectional-and-longitudinal-studies.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Deploy-to-a-server-installation.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/End-page-after-your-study-finished.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Manage-Results.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Restricting-study-flow.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Run-your-Study-with-Study-Links.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Study-Log.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Tips-and-Tricks.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Use-Prolific.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/Worker-Types.md create mode 100644 versioned_docs/version-3.9.1/Run_your_study/_category_.json create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/Bring-your-JATOS-online.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/Expose-your-local-JATOS.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/Install-JATOS-via-Docker.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-a-cluster.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-on-DigitalOcean.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-on-a-server.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Apache.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Docker-Compose.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-MySQL.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md create mode 100644 versioned_docs/version-3.9.1/Serving_the_Internet/_category_.json create mode 100644 versioned_docs/version-3.9.1/Write_your_study/Adapt-pre-written-code-to-run-it-in-JATOS.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/Change-studys-members.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/Combine_two_pre_written_studies_into_one.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/Create-a-new-study.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/OSWeb-and-JATOS.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/Session-Data-Three-Types.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/Submit-and-upload-data-to-the-server.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/Write-your-own-Study-Basics-and-Beyond.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/_category_.json create mode 100644 versioned_docs/version-3.9.1/Write_your_study/jsPsych-and-JATOS.md create mode 100644 versioned_docs/version-3.9.1/Write_your_study/labjs-and-JATOS.md create mode 100644 versioned_sidebars/version-3.9.1-sidebars.json diff --git a/docusaurus.config.js b/docusaurus.config.js index 39eb543143..492418b92b 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -28,16 +28,21 @@ const config = { routeBasePath: '/', showLastUpdateAuthor: true, showLastUpdateTime: true, - lastVersion: '3.8.1', + lastVersion: '3.9.1', versions: { current: { label: 'next', path: 'next', banner: 'unreleased', }, + '3.9.1': { + label: '3.9.x', + path: '', + banner: 'none', + }, '3.8.1': { label: '3.8.x', - path: '', + path: '3.8.x', banner: 'none', }, '3.7.1': { diff --git a/versioned_docs/version-3.9.1/Group_studies/Example-Group-Studies.md b/versioned_docs/version-3.9.1/Group_studies/Example-Group-Studies.md new file mode 100644 index 0000000000..f75743920d --- /dev/null +++ b/versioned_docs/version-3.9.1/Group_studies/Example-Group-Studies.md @@ -0,0 +1,28 @@ +--- +title: Example Group Studies +slug: /Example-Group-Studies.html +sidebar_position: 1 +--- + +In group studies, the workers that are part of a group can communicate with each other. JATOS supports different kinds of groups. A group can e.g. have a fixed set of workers like this [Prisoner's Dilemma](/Example-Studies) where exactly two workers play with each other. On the other side of the spectrum is this [Snake game](/Example-Studies) with an on open, multi-worker approach. + +**How can you try-out a group-study if you're alone but want to simulate multiple workers?** + +JATOS allows [up to 10 study runs](Tips-and-Tricks.html#run-up-to-10-studies-in-the-same-browser-at-the-same-time) at the same time in the same browser (JATOS has no limit for different browsers). So you can just start the same (group) study multiple times in your browser and pretend you're multiple workers. + +As an example of this, let's go through the Snake Game group study in detail: + +1. Download and import the [Snake game](/Example-Studies) +1. Open the [Study Links](Run-your-Study-with-Study-Links.html) page +1. Now get a study link to start the first Snake game: Click on the Study Links button in line Personal Multiple (other study link types are fine too). In the opened pop-up window click on the top-left button to get a new link and then on in the link's row to copy it to the clipboard. +1. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start. +1. Repeat the last step to start a second Snake game. +1. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click **Join** and then **Ready**. +1. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group. +1. Optional: Have a look at your [Group in the Study Links page](Run-your-Study-with-Study-Links.html#groups) add see who the member workers are. + +![Snake example](/img/example-studies/Screenshot_snakeGame.png) + +There's actually a lot going on behind the curtain of a group study. All members of a group are able to communicate in real-time with each other directly or broadcast messages to the whole group. + +Next step: [Write Your Own Group Studies](Write-Group-Studies-I-Setup.html). diff --git a/versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-I-Setup.md b/versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-I-Setup.md new file mode 100644 index 0000000000..fea712b377 --- /dev/null +++ b/versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-I-Setup.md @@ -0,0 +1,55 @@ +--- +title: Write Group Studies I - Setup +slug: /Write-Group-Studies-I-Setup.html +sidebar_position: 2 +--- + +## Set up group studies + +First and common to all group setups is to check the Group study checkbox in the study properties. + +![Group's property](/img/v39x/study-properties-group-study.png) + +If the Group property is checked, JATOS will assign workers into groups. We'll describe some group properties that you can use to tweak according to whether you want to keep control over worker assignment, or you give JATOS full control. + + +### Group settings in each batch's properties + +You can have multiple batches in JATOS, each one with different group settings. There are three important bits of information for a group study: + +![Study Links screenshot](/img/v39x/batch_properties_groups.png) + +1. **Max total workers**: This isn't just a properties of group studies. It simply limits the total amount of workers who are allowed to run in this batch. +1. **Max total members**: This limits the number of members a single group can have. While there can be multiple groups in a batch, the _Max total members_ field applies to each separate group. +1. **Max active members**: This limits the number of active members a single group can have. An active member is in the group at this time - in opposite to a past member who already left the group. This number applies to each group separately. Example: In the Prisoner's Dilemma study, you would limit the active members to 2. + +By default, all properties have no upper limit. + + +## Group assignment + +You can either tell JATOS to assign workers to different groups, or you can keep full control and do it yourself (or something in between). We'll use some example scenarios to explain how this assignment works. + +### Scenario 1: One group, assign workers manually + +If in a batch you set the _Max total worker_ to 2 and leave the other two Max parameters empty, JATOS has no other choice than to allow only 2 workers and sort them into the same group. If you then [create two Personal Single study links](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send the links to your two participants, you can be sure that they will interact with each other. If you need more groups, just create a second batch with two other workers. + +![Prisoners example](/img/prisoners_example.png) + +The first two scenarios may apply to the [Prisoner's Dilemma Example Study](/Example-Studies). + +### Scenario 2: Several groups, let JATOS assign workers + +Say you want to have 3 groups with 2 workers each. You want to leave it to JATOS which workers are paired together. Then, set _Max total workers_ to 6 and both _Max active members_ and _Max total members_ to 2 (remember that these numbers apply to each group separately). Then [create 6 Personal Single study links](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send them to your 6 participants. + +### Scenario 3: One open world + +This scenario is basically the opposite of the first one. By limiting neither the _Max total worker_ nor the _Max total members_, nor the _Max active members_ JATOS will sort all workers into one single group that is potentially of unlimited size. Now --to keep it completely open-- just [create one study link type General Single](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website). + +![Snake example](/img/snake_example.png) + +The third and fourth scenario may apply to the [Snake Example Study](/Example-Studies). + +### Scenario 4: Multiple open worlds with limited active members + +Say you want to have groups with up to 3 members, interacting _at the same time_. But you don't want to actually limit the total number of members per group: you want to allow new workers to join a group if one of its members left. This way each group can have a flow of workers joining and leaving - the only constraint is the maximum members per group at any given time. You also want to let JATOS set the number of groups depending on the available workers. To set up this just use one batch, set the _Max active members_ to 3, and leave _Max total worker_ and _Max total members_ unlimited. diff --git a/versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-II-JavaScript-and-Messaging.md b/versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-II-JavaScript-and-Messaging.md new file mode 100644 index 0000000000..8a408bf960 --- /dev/null +++ b/versioned_docs/version-3.9.1/Group_studies/Write-Group-Studies-II-JavaScript-and-Messaging.md @@ -0,0 +1,66 @@ +--- +title: Write Group Studies II - JavaScript and Messaging +slug: /Write-Group-Studies-II-JavaScript-and-Messaging.html +sidebar_position: 3 +--- + +## Writing JavaScripts for group studies + +Group studies differ from single-worker studies simply in that the JavaScript needs to handle groups and communications between members. The _jatos.js_ library provides some useful functions for this. + +If you like to dive right into _jatos.js'_ reference: + +* [_jatos.js_ functions for group studies](jatos.js-Reference.html#group-functions) +* [_jatos.js_ group variables](jatos.js-Reference.html#group-variables) +* [_jatos.js_ Group Session functions](jatos.js-Reference.html#functions-to-access-the-group-session) + + +### Joining a group and opening group channels + +Workers can only communicate with members of their own group. So, interacting workers must all join the same group. +**A worker will remain in a group until _jatos.js_ is explicitly told to leave the group (or the study run is finished). This means that if a worker moves between components or reloads a page they will still remain in the same group.** This feature makes groups much more robust. + +So here's how a typical JATOS group study run would look like. This study has three components. + +Component 1 + + * `jatos.joinGroup` -> joins group and opens group channel + * `jatos.nextComponent` -> closes group channel and jumps to next component + +Component 2 + + * `jatos.joinGroup` -> opens group channel in the **same group** + * `jatos.nextComponent` -> closes group channel and jumps to next component + +Component 3 + + * `jatos.joinGroup` -> opens group channel **same group** + * `jatos.endStudy` -> closes group channel, leaves group, ends component, and ends study + +Notice that by calling [`jatos.joinGroup`](jatos.js-Reference.html#jatosjoingroup) in the second and third component JATOS does not let workers join a new group but just opens a group channel in the already joined group. To make a worker leave a group, use the function [`jatos.leaveGroup`](jatos.js-Reference.html#jatosleavegroup). + +Every know and then you probably would like to know who the members of your groups are. This and other stats you can get by clicking on your batch's [Groups button in the Study Links page](Run-your-Study-with-Study-Links.html#groups). + + +### Reassigning to a different group + +To move a worker from one group to a different one, use [`jatos.reassignGroup`](jatos.js-Reference.html#jatosreassigngroup). This function will make a worker leave their group and join a different one. JATOS can only reassign to a different group if there is another group available. If there is no other group JATOS will not start a new one but put the worker into the same old group again. + +### Fixing a group + +Sometimes you want to stay with the group like it is in this moment and don't let new members join - although it would be allowed according to the group properties. For example in the [Prisoner's Example study](/Example-Studies) after the group is assembled in the waiting room component it is necessary to keep the two members as it is. Even if one of the members leaves in the middle of the game, JATOS shouldn't just assign a new member. To do this you can call _jatos.js_' function [`jatos.setGroupFixed`](jatos.js-Reference.html#jatossetgroupfixed). Alternatively you can fix a group in JATOS' GUI, in the +[Groups table in the Study Links page](Run-your-Study-with-Study-Links.html#groups). + + +## Communication between group members + +JATOS provides three ways for communicating within the group: direct messaging, broadcast messaging and with the Group Session. + +### Direct messaging +Members can send direct messages to a single other member of the same group with the [`jatos.sendGroupMsgTo`](jatos.js-Reference.html#jatossendgroupmsgto) function. Like broadcast messaging this way of group communication is fast but can be unreliable in case of an unstable network connection. We use direct messaging in the [Snake example](/Example-Studies) to send the coordinates of the snakes on every step. Here, speed is more critical than reliability in the messages, because a few dropped frames will probably go unnoticed. + +### Broadcast messaging +Members can send messages to all other members of the same group with the [`jatos.sendGroupMsg`](jatos.js-Reference.html#jatossendgroupmsg) function. Like direct messaging this way of group communication is fast but can be unreliable in case of an unstable network connection. + +### Group session +The Group Session is one of the [three types of session that JATOS provides](Session-Data-Three-Types.html). Members can access the Group Session data with the [Group Session functions](jatos.js-Reference.html#functions-to-access-the-group-session). The Group Session data are stored in JATOS' database **only while the group is active. It is deleted when the group is finished.** Communication via Group Session is slower, but more reliable than group messaging. If one member has an unstable internet connection or does a page reload, the Group Session will be automatically restored after the member reopens the group channel. Workers communicate via the Group Session data in the [Prisoner's Example study](/Example-Studies), because here one dropped message would lead to important information loss. diff --git a/versioned_docs/version-3.9.1/Group_studies/_category_.json b/versioned_docs/version-3.9.1/Group_studies/_category_.json new file mode 100644 index 0000000000..69e5680a14 --- /dev/null +++ b/versioned_docs/version-3.9.1/Group_studies/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Group studies", + "position": 5 +} diff --git a/versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md b/versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md new file mode 100644 index 0000000000..32bb23f92d --- /dev/null +++ b/versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md @@ -0,0 +1,32 @@ +--- +title: Administration +slug: /Administration.html +sidebar_position: 1 +--- + +On the Administration page [users with admin rights](/User-Manager.html) can get an overview of the studies and users of a JATOS installation. You can see the **logs**, **system info**, or go to the **test page** to check if JATOS runs correctly. It is also the place where **update notifications** appear when a new JATOS version is available and where [admins can trigger an update](/Update-JATOS.html#automatic-updates). + +![Administration screenshot](/img/v39x/administration.png) + + +### User Manager + +Manage users, passwords, and rights from here. Find more details on [its documentation page](/User-Manager.html) + + +### Study Administration + +By clicking the _Studies_ button you'll get to an overview about all studies that are on the JATOS instance. You'll also see, for each study: whom it belongs to (the study members), how much disk space it takes, and when it was active last. + +**In larger JATOS installations it can take up to a couple minutes to gather all data for this page** + +![Studies Administration](/img/v39x/study_manager.png) + +The information is displayed in a table with the columns: + +* **Active** - In cases where e.g. a study uses to many server resources, an admin can **deactivate** (or activate again) it by clicking the checkbox in the 'Active' column. A deactivated study cannot be started by participants (workers) anymore, but an already started study run can be continued. That means, an admin will not interrupt a participant if they already started doing a study, but no new participants will be able to start it. The study members can still see and edit the study, as well as export its result data. +* **Study Assets Size** - The disk size of all asset files associated to this study (HTML, JS, CSS, images, videos, etc.). +* **Result Count** - The number of study results collected so far on this JATOS instance. +* **Result Data Size** - The size of all result data that are stored in the database. In brackets is the average size per result count. +* **Result File Size** - The size of all result files that are stored in the server's file system. In brackets is the average size per result count. +* **Last Started** - When was this study last started by a participant. diff --git a/versioned_docs/version-3.9.1/Manage_your_JATOS/Customize-JATOS-Home-Page.md b/versioned_docs/version-3.9.1/Manage_your_JATOS/Customize-JATOS-Home-Page.md new file mode 100644 index 0000000000..bebf04ecf5 --- /dev/null +++ b/versioned_docs/version-3.9.1/Manage_your_JATOS/Customize-JATOS-Home-Page.md @@ -0,0 +1,56 @@ +--- +title: Customize JATOS' Home Page +slug: /Customize-JATOS-Home-Page.html +sidebar_position: 5 +--- + +## Link to Terms of Use + +You can configure JATOS to show a link to your 'Terms of Use' that will be shown in a info box on the home page. + +In your JATOS installation folder edit `conf/jatos.conf` (or `conf/production.conf` in version < 3.8.3) and add the URL under `jatos.termsOfUseUrl`. If left empty the info box is not shown. + + +## Welcome Block + +You can customize JATOS' home page to e.g. +* show your university's logo, +* add some introduction text, or +* announce an upcoming event. + +This is done by configuring JATOS with an URL that points to some static HTML that describes your individual welcome block. This HTML block will then be loaded and displayed in every home page. + +Have a look at this [example welcome block](https://github.com/JATOS/customized-home-page-template/blob/main/foobar-university-welcome.html). + + +![template customized home page](/img/v39x/screenshot-branding.png) + +You can update your welcome block at any time to add new information (e.g. anouncement of JATOS maintance work). But since the HMTL is cached it can take **up to an hour to be visible to your users**. If you want to see it right away for testing you can disable caching in your browser. + +This welcome block can be fetched from **any HTTP server** that is able to serve HTML. One way is to do it via GitHub. + +### With GitHub + +1. Go to [https://github.com/JATOS/customized-home-page-template](https://github.com/JATOS/customized-home-page-template) +1. Click 'Use this template' button to create a copy of this repository +1. Change the content of `foobar-university-welcome.html` to your needs +1. Add necessary files (e.g. logo images) to your repository +1. Configure JATOS: In your JATOS installation folder edit `conf/jatos.conf` (or `conf/production.conf` in version < 3.8.3) - add `jatos.brandingUrl`: + + 1. Easy but with rate limit (from GitHub) + + ``` + jatos.brandingUrl = "https://raw.githubusercontent.com/my-user/my-repo/main/foobar-university-welcome.html" + ``` + + Remember to change `my-user`, `my-repo`, and `foobar-university-welcome.html` + + 1. Better use [GitHub pages](https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site) + + ``` + jatos.brandingUrl = "https://my-user.github.io/my-repo/foobar-university-welcome.html" + ``` + + Remember to change `my-user`, `my-repo`, and `foobar-university-welcome.html` + +1. Restart JATOS diff --git a/versioned_docs/version-3.9.1/Manage_your_JATOS/Troubleshooting.md b/versioned_docs/version-3.9.1/Manage_your_JATOS/Troubleshooting.md new file mode 100644 index 0000000000..15b5563ff0 --- /dev/null +++ b/versioned_docs/version-3.9.1/Manage_your_JATOS/Troubleshooting.md @@ -0,0 +1,44 @@ +--- +title: Troubleshooting +slug: /Troubleshooting.html +sidebar_position: 4 +--- + +### JATOS test page + +JATOS comes with build in tests (e.g. WebSockets connections and database connection), but they are only accessible for users with admin rights: go to _Administration_ ⇒ _Tests_ and check that all tests are 'OK'. + + +### Downloading a study / exporting a study fails (e.g. in Safari browsers) + +As a default, Safari (and some other browsers) automatically unzips every archive file after downloading it. When you export a study, JATOS zips your study together (study properties, all components, and all files like HTML, JavaScripts, images) and delivers it to your browser, who should save it in your local computer. Safari's default unzipping interferes with this. Follow [these instructions](https://discussions.apple.com/thread/1958374?start=0&tstart=0) to prevent Safari's automatic unzip. + + +### Read log files in the browser + +In a perfect world, JATOS always works smoothly and, when it doesn't, it describes the problem in an error message. Unfortunately we aren't in a perfect world: every now and then something will go wrong and you might not get any clear error messages, or no message at all. In these (rare) cases, you can look into JATOS' log files (not to be confused with the [study log](Study-Log.html)) to try to find what the problem might be. You can see and download all log files in the _Administration_ page => _Logs_ (for security reasons, you must be logged in as a user with admin rights). + +* _application.log_ - all JATOS logging +* _loader.log_ - logging during startup with loader +* _update.log_ - logging during updates + +Alternatively you can read the log files directly on the server. You'll find your logs in `jatos_directory/logs/`. + + +### A file (library, image, ...) included in the HTML fails to load? + +There is a common mistake Windows users make that might prevent files from loading: Any URL or file path in a HTML or JS file should only use '/' as a file path separator - even on Windows systems. So it should always be e.g. `` and **not** ``. + + +### Database is corrupted? + +If you get an error that reads something like: `Error in custom provider, Configuration error: Configuration error[Cannot connect to database [default]]`, your database might be corrupted. By default JATOS comes with an H2 database and the H2 database doesn't handle [copying its files while running](http://stackoverflow.com/questions/2036117/how-to-back-up-the-embedded-h2-database-engine-while-it-is-running) too well. + +There are two reasons why this might be the case: you moved your JATOS folder while it was running or you installed JATOS in a synced folder. To prevent this, be sure to always be careful with the following: + +1. **Don't copy or move while JATOS is running** - Always **stop JATOS** (type `./loader.sh stop` in your Linux / Mac OS terminal or close the window on Windows) before moving it. +1. **Don't sync while JATOS is running** - As we mentioned in the [Installation page](Installation.html), you can run JATOS from pretty much anywhere **except** from a folder that syncs across devices, like Dropbox or Google Drive. Doing so might lead to database corruption, because while the files might be synced between computers, the running processes aren't. This will lead to havoc and destruction and, in extreme cases, to the implosion of the known Universe. You can find in our [blog post](http://blog.jatos.org/Database_Recovery/) a description of an attempt to recover a corrupted database. Didn't work. + +**Of course, this brings us to an important point: back up your result data (i.e., simply download and save your text files) regularly if you're running a study!** + + diff --git a/versioned_docs/version-3.9.1/Manage_your_JATOS/Update-JATOS.md b/versioned_docs/version-3.9.1/Manage_your_JATOS/Update-JATOS.md new file mode 100644 index 0000000000..64aed8ba62 --- /dev/null +++ b/versioned_docs/version-3.9.1/Manage_your_JATOS/Update-JATOS.md @@ -0,0 +1,132 @@ +--- +title: Update JATOS +slug: /Update-JATOS.html +sidebar_position: 3 +--- + +We'll periodically update JATOS with new features and bug fixes. We recommend you stay up to date with the [latest release](https://github.com/JATOS/JATOS/releases). However if you are currently running a study it's always safest to keep the same JATOS version throughout the whole experiment. + +**Please do backups before updating.** + +**Be aware: JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation.** + +There are more details about updating in their respective pages: + +* [Update JATOS running on a server](/JATOS-on-a-server.html#update-jatos) +* [Update JATOS running in a Docker container](/Install-JATOS-via-Docker.html#updating-jatos-with-docker) +* [Update JATOS running with Docker Compose](/JATOS-with-Docker-Compose.html#updating-jatos-with-docker-compose) +* [Update JATOS running with Kubernetes](/JATOS-in-a-cluster.html#updating-jatos-with-kubernetes) + + +## Automatic Update + +This is the recommended update method for JATOS running locally or on a simple server (but not in a cluster). + +You can update your JATOS automatically if you have **admin rights** on JATOS and running on **Mac OS** or **Linux**. **Windows is not yet supported**. + +The process is pretty self-explanatory, but anyway, we'll explain it here in detail: + +1. You will get a notification on your JATOS' _Administration_ page. + + ![Update notification Schreenshot](/img/v39x/autoupdate-notification.png) + + Sometimes your JATOS is not able to receive data about new releases. Often a restart of the JATOS application helps in this case. If this still persists and you know there is a new release that you would like to update to, you can still [start the update by specifying the version](/Update-JATOS.html#auto-update-to-a-specific-version). + +1. Click on _Update_, confirm that you want to continue and the latest JATOS version will be downloaded from GitHub and saved in your system's temporary folder. The download might take a while depending on your internet connection. + + ![Update notification Schreenshot](/img/v39x/autoupdate-confirmation.png) + +1. After download is complete, you will be asked again for confirmation. + + ![Update notification Schreenshot](/img/v39x/autoupdate-update-and-restart.png) + +1. After clicking the _Go on_ button, JATOS will stop itself, replace its program files and re-start itself again. This might take some time depending on the new version and your machine resources, but usually it's done within 2 minutes. Refresh your JATOS home page every now and then until you see your updated JATOS' login screen again. + +1. Check the new JATOS with the build-in tests: go to _Administration_ ⇒ _Tests_ and check that all tests are 'OK'. + + +### (Auto-)Update to a specific version + +Sometimes, for whatever reasons, JATOS doesn't automatically detect new versions. Then you can still start the update by specifying the version. + +**It is usually destructive to update JATOS to a lower version than is currently installed. It's highly recommended to use a higher version (or the same). Use at your own risk.** + +The URL of JATOS administration page accepts the query parameter `version`. This parameter takes the JATOS version as specified in [GitHub](https://github.com/JATOS/JATOS/releases) and enforces an update to this version. + +E.g. if the version you want to update to is `v3.9.1` (don't forget the 'v') and your domain is `my.jatos.org`, than the URL for your browser is: + +``` +https://my.jatos.org/jatos/admin?version=v3.9.1 +``` + +The rest of the update procedure is the same as in the normal automatic update: you will be asked for confirmation twice. + +--- + +JATOS uses Java 11 - older versions use Java 8. Future versions will likely require newer Java versions. If you're updating from a JATOS version using Java 8 to (say) another version using Java 11, the auto-update process will automatically download JATOS bundled with the new Java, regardless of which variant you are currently using. If you do not like the bundled Java and use your own version you can always remove the folder _jre_ later on after the update. + +--- + + +## Manual Update + +The automatic update is the preferred way but if, for whatever reason, you do not trust JATOS' automatic update or it does not work for you (e.g. you run a server on Windows), you can still update JATOS manually. + +You can update your JATOS manually in two main ways: 1) Easy, but discarding all results, and 2) Not so easy, but keep everything. + + +### Easy, but discard results + +If you don't care about result data stored in JATOS: + +1. Export any studies you wish to keep from the old JATOS installation. +1. Download and install the new version as if it were a new fresh installation. Don't start it yet. +1. Stop the old JATOS and start the new JATOS. +1. Import all the studies your previously exported. This will transfer the files and subfolders in your study's asset folder (HTML, JavaScript, CSS files). + +**What will be transferred:** + +1. Files and subfolders in study's assets folder +1. All your studies' and components' properties +1. The **properties** of the first (Default) batch + +**What will be lost:** + +1. **All result data and files will be lost** +1. All workers in all batches (including Default batch) +1. All batches other than the Default batch +1. Any configuration you did in _jatos.conf_ +1. All study logs + + +### Not so easy, but keep everything + +JATOS stores its state in several folders in the file system and a database and you will have to transfer everything to the new, updated JATOS. + +* The **_study assets root_ folder** stores all your study's files (e.g. HTML, JS, CSS, images). By default it's in your JATOS folder and has the name _study_assets_root_. +* The **_result uploads_ folder** stores all your study result files. By default it is in your JATOS folder and has the name _result_uploads_. +* The **_study logs_ folder** stores all your study logs. By default it is in your JATOS folder and has the name _study_logs_. +* JATOS' **_application logs_** are stored by default in your JATOS folder under a folder with the name _logs_. +* If you use the **_embedded database_** then all its data is, by default, stored in a folder called _database_ within your JATOS folder. +* If you use a **_MySQL/MariaDB database_** your data are stored there and you only have to configure the updated JATOS to use this database. +* You might have configured JATOS by changing it's **_jatos.conf_ file**. By default it is in the JATOS installation folder in the folder _conf_. + +**Then the update procedure is:** + +1. Stop JATOS. +1. Download and install the new version as if it were a new fresh installation. Don't start it yet. +1. From the folder of your old JATOS installation copy the **_study assets root_ folder**, **_result uploads_ folder**, **_study logs_ folder**, **_application logs_ folder**, the **_database_ folder** (if you do not use MySQL/MariaDB), and the **_jatos.conf_** into the folder of your new, updated JATOS. +1. Start the new JATOS. + +**What will be transferred:** + +1. All study assets +1. All your study and component properties +1. All batches, together with their workers, and generated study links +1. All result data and files +1. All study logs +1. All logs +1. JATOS' configuration (as long as it is done in the configuration file) + +**What will be lost:** +nothing \ No newline at end of file diff --git a/versioned_docs/version-3.9.1/Manage_your_JATOS/User-Manager.md b/versioned_docs/version-3.9.1/Manage_your_JATOS/User-Manager.md new file mode 100644 index 0000000000..68dd403edf --- /dev/null +++ b/versioned_docs/version-3.9.1/Manage_your_JATOS/User-Manager.md @@ -0,0 +1,75 @@ +--- +title: Manage JATOS users +slug: /User-Manager.html +sidebar_position: 2 +--- + +Each experimenter with access to the JATOS server (though the GUI) is a JATOS User. Users can create, modify and delete the studies they are members of. They can also export and delete results. Users may also have special roles: **Admin** or **Superusers**. Only Admin users have access to the [_Administration_ page](Administration.html) and control other users' access to JATOS. Superusers exist only since JATOS version 3.7.4 and they can access all studies on this JATOS including their result data. + + +## Manage users + +Only users with admin rights have access to the **User Manager** (in the _Administration_ page). From the _User Manager_, admins can create new users or delete existing ones, or change passwords. Admins can also deactivate/activate users and see information about the user's studies. + +JATOS comes with one **Admin user** out-of-box (username: 'admin'). User Admin always has admin rights that cannot be revoked. The initial password for Admin is 'admin' and it should be changed immediately after installation and kept safe! + +Every user can be granted Admin rights, by checking the corresponding box in the _Admin_ column of the table. Only admins can access the _Administration_ pages (like _User Manager_ or _Study Info_). + +![User manager screenshot](/img/v39x/user_manager_3.png) + +A user can be **deactivated** (and activated again) by clicking the checkbox in the 'Active' column. A deactivated user cannot log in anymore but their studies can still be run by participants (to prevent a study from running, deactivate it in the study _Administration_ page). + +If you're an admin and need to get more information about a user's studies, click on the _Studies_ column. You'll see _Result Data Size_ and _Result File size_, which can give you an idea of how many of the server's resources this user needs. + +![User manager screenshot](/img/v39x/user_manager_4.png) + +Clicking on the _Export_ button on the top of the page, you can export user data in CSV format. This is useful to e.g. get a list of emails if you need to notify all users about a server downtime, JATOS update, etc. + + +## Superusers + +By default the ability to turn a user into a Superuser is deactivated and has to be activated in `conf/jatos.conf` (or `conf/production.conf` in version < 3.8.3) by adding: + +``` +jatos.user.role.allowSuperuser = true +``` + +Then every user can be granted the Superuser role by checking the corresponding box in the _Superuser_ column of the table. + +Superusers can access all studies on this JATOS instance regardless if they were added as a member user. This includes changing the study properties, accessing the result data or deleting the study. This is useful for single-lab or training JATOS installations where one user needs fast access to everything to help other researchers or students. However unlike Admin users Superusers cannot access the Administration page or manage other users. + + +## Authentication via LDAP + +JATOS allows password authentication via LDAP (which lets an institution manage their users in a centralized way). LDAP is disabled by default. To enable it [change the JATOS config file](JATOS_Configuration.html#ldap-authentication). + +Once LDAP is enabled, there will be an additional checkbox 'LDAP' on the overlay dialog when an admin creates a new user. Check this box to enforce authentication by LDAP. Normal JATOS users (locally authenticated) and LDAP users can co-exist in the same JATOS instance. + +At the moment it is not possible to let JATOS create LDAP users automatically - they must be created by an JATOS admin manually. + + +## Authentication via Google Sign-In + +Google Sign-In is deactivated by default and can be activated by adding your Google Client-ID in the `conf/jatos.conf` (or `conf/production.conf` in version < 3.8.3), similar to this: + +``` +jatos.user.authentication.oauth.googleClientId = "1234567890-abc123abc123.apps.googleusercontent.com" +``` + +If a new user authenticates the first time with Google Sign-In the user will be automatically created in JATOS. This means a 'Google' user cannot be created by a JATOS Admin. + + +## Authentication via OpenId Connect (OIDC) + +Since version 3.8.5 JATOS users can be authenticated by [OIDC](https://openid.net/developers/how-connect-works/). OIDC is an authentication protocol that offers an easy-to-use sign in button. It needs an OIDC provider that is not part of JATOS (e.g. [Keycloak](https://www.keycloak.org/)). You can find more about [how to configure JATOS to use OIDC](/JATOS_Configuration.html#openid-connect-oidc) in the JATOS configuration page. + +If a new user authenticates the first time with OIDC the user will be automatically created in JATOS. This means an OIDC user cannot be created by a JATOS Admin. + + +## Authentication via ORCID (orcid.org) + +Since version 3.8.5 JATOS users can be authenticated by [ORCID sign-in](https://info.orcid.org/documentation/features/public-api/orcid-as-a-sign-in-option-to-your-system/). ORCID offers an easy way to configure and use a _Sign in with ORCID_ button. + +You only need to set two parameters in JATOS' configuration to make your JATOS use ORCID's authentication: your ORCID _client ID_ and _client secret_. Read [here](https://info.orcid.org/documentation/integration-guide/registering-a-public-api-client/) more about how to get these (but the short version is: Go to your ORCID user page -> expand your username top right: click _Developer Tools_). Then [configure your JATOS with your client ID and secret](/JATOS_Configuration.html#orcid-orcidorg-authentication). + +If a new user authenticates the first time with ORCID the user will be automatically created in JATOS. This means an ORCID user cannot be created by a JATOS Admin. \ No newline at end of file diff --git a/versioned_docs/version-3.9.1/Manage_your_JATOS/_category_.json b/versioned_docs/version-3.9.1/Manage_your_JATOS/_category_.json new file mode 100644 index 0000000000..b5f28bba85 --- /dev/null +++ b/versioned_docs/version-3.9.1/Manage_your_JATOS/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Manage your JATOS", + "position": 4 +} diff --git a/versioned_docs/version-3.9.1/Overview/Contact-us.md b/versioned_docs/version-3.9.1/Overview/Contact-us.md new file mode 100644 index 0000000000..059511540c --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/Contact-us.md @@ -0,0 +1,40 @@ +--- +title: Contact us +slug: /Contact-us.html +sidebar_position : 3 +--- + +JATOS is under active development, so please do get in touch to ask questions, suggest enhancements and report bugs. We really appreciate any contributions. + +We also conduct workshops: If you want us to give a lecture or workshop about JATOS and/or online studies in general contact us via email. + + +**If you have a question about JATOS or need help with your experiments, write to either:** + + +### CogSci forum + +JATOS has a subforum in the very nice [CogSci.nl](https://forum.cogsci.nl/categories/jatos) forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication. + + +### Slack + +Get an invite to [JATOS Slack workspace](https://communityinviter.com/apps/jatosworkspace/jatos-slack). + + +### GitHub issues + +If you would like to report a bug or suggest a new feature that could improve JATOS, you could write a [GitHub issue](https://github.com/JATOS/JATOS/issues). + + +### Google Groups + +[Google Groups](https://groups.google.com/forum/#!forum/jatos) + + +### Email +If for some reason you don't want to use the public group or CogSci forum you can also write us directly. (But we prefer that you use any of the other two options as your question might help others. We get notified of new posts immediately.). + +elisa.filevich@jatos.org + +kristian.lange@jatos.org diff --git a/versioned_docs/version-3.9.1/Overview/Data-Privacy-and-Ethics.md b/versioned_docs/version-3.9.1/Overview/Data-Privacy-and-Ethics.md new file mode 100644 index 0000000000..9d74d6c0ef --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/Data-Privacy-and-Ethics.md @@ -0,0 +1,94 @@ +--- +title: Data Privacy and Ethics +slug: /Data-Privacy-and-Ethics.html +sidebar_position: 7 +--- + +### What does JATOS store? + +Data privacy is a critical issue in online studies. You should be careful when collecting, storing and handling data, regardless of which platform you use to run your studies. + +We developed JATOS with data privacy in mind, preventing any breaches of the standard ethical principles in research. However, ultimately you are responsible for the data you collect and what you do with it. + +![GUI Screenshot](/img/IMG_1376.JPG) + +(copyright 2006 John klossner, www.jklossner.com) + +Here are a few advantages and limitations of JATOS with regards to data privacy. Please read them carefully before you run any study, and please [contact us](Contact-us.html) if you find that these are not sufficient, or have suggestions for improvement. + +* JATOS' main advantage is that you can store your participants' data in your own server (e.g. at your university). This means that you have full control over the data stored in your database, and no commercial company has access to it. JATOS does not share any data (except of course during a study run with the participant's browsers). Each JATOS installation is completely independent of any other JATOS installation. + +* By default, JATOS stores the following data: + * time (of the server running JATOS) at which the study -and each of its components- was started and finished + * the [worker type](Worker-Types.html) (MTurk, General single, Personal multiple, etc) + * in cases of MTurk workers, the confirmation code AND the MTurk worker ID. In these cases, if an MTurk worker participated in two of your studies, running in the same JATOS instance, **you will be able to associate the data across these two studies**. This is an important issue: MTurk workers might not be aware that you are the same researcher, and will not know that you have the chance to associate data from different studies. The best way to avoid this is to export all your study's data and delete it from the JATOS database once you are done with it. In this way, JATOS won't know that a worker already participated in another study and will create a new worker ID for them. + +* JATOS will **not** store information like IP address or browser type (User-Agent or any other HTTP header field). + +### Things you should consider in your studies + +* You should consider to add some button in your study pages to abort the study. Some ethics demand that any participant should have the **right to withdraw** at any time, without explanation. In this case all data of the participant gathered during the study should be deleted. Conveniently _jatos.js_ offers the functions [`jatos.abortStudy`](jatos.js-Reference.html#jatosabortstudy) and [`jatos.addAbortButton`](jatos.js-Reference.html#jatosaddabortbutton) that do exactly that. + +* Use **encryption** with your [server instance](JATOS-on-a-server.html). Only with encryption no one else in the internet can read the private data from your study's participants. + +* JATOS will **not** store information like IP address or browser type (nor any other HTTP header field). However, you could access and store this information through your JavaScripts. You could also record whether workers are actively on the browser tab running your study, or whether they have left it to go to another tab, window or program. If you collect any of these data, you should let your workers know. + +* Bear in mind: Every file within your study assets folders is public to the Internet. Anybody can in principle read any file in this folder, regardless of how secure your server is. **Thus, you should never store any private data, such as participants' details in the study assets folders.** + +* **Do not store private information in the Batch Session or Group Session.** Both sessions are shared between all members of a batch or group respectively. If you store private data any other member of this batch or group could potentially access it. Since the Study Session is only shared within the same study run it is not a problem to store private information there. + +### Cookies used by JATOS + +Sometimes it is neccessary to specify which cookies are stored in a participants browser. JATOS knows three types of cookies and only two of them are stored in a participants browser. + +#### 1. Up to ten JATOS ID cookies with cookie name JATOS_IDS_* (* can be a number from 0 to 9) + +These cookies store values about each study run. JATOS allows up to 10 study runs in parallel per browser - therefore there are up to 10 JATOS ID cookies. + +All IDs are used only by JATOS internally and do not allow the identification of the worker. + +The cookie virtually never expires (actually far in the future, around the year 2086). + +[HttpOnly](https://www.owasp.org/index.php/HttpOnly) is set to false (this means, it can be read by JavaScript in the browser). + +This cookie contains these parameters: + +* _studyId_: identifier of the study +* _batchId_: identifier of the batch +* _componentId_: identifier of the component +* _componentPos_: position of the component within the study +* _workerId_: identifier of the worker used internally to identify the worker anonymously +* _workerType_: there are [5 worker types with different use cases in JATOS](Worker-Types.html) +* _componentResultId_: identifier of the component result (a component result is used to store data of the component run) +* _studyResultId_: identifier of the study result (a study result is used to store data of this study run) +* _studyResultUuid_: universial identifier of the study result (a study result is used to store data of this study run) +* _groupResultId_: identifier of the group this worker belongs to (null if it isn't a group study) +* _creationTime_: timestamp (epoch time) of this cookie's creation +* _studyAssets_: name of the directory where the study's assets are stored on the JATOS server +* _jatosRun_: State of a study run with a JatosWorker. If this run doesn't belong to a JatosWorker this field is null. It's mainly used to distinguish between a full study run and just a component run. +* _urlBasePath_: [Base path under which JATOS resides](JATOS_Configuration.html#url-base-path-jatos) + +E.g. `batchId=1&componentId=1&componentPos=1&componentResultId=35&creationTime=1639502424728&studyAssets=jatosjs_test_study&urlBasePath=/&jatosRun=RUN_STUDY&groupResultId=null&studyId=1&studyResultId=33&studyResultUuid=7d5b3da2-b0bf-4e22-98bc-f0e5d7752c00&workerId=1&workerType=Jatos` + +#### 2. Cookie JATOS_GENERALSINGLE_UUIDS + +This cookie is used by JATOS to store which study runs with a [General Single worker](Worker-Types.html#general-single-worker) already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID). + +#### 3. Play Framework session cookie named PLAY_SESSION + +This cookie is used only by JATOS' GUI and provides session and user info. It is **not** set during a study run and therefore does **not** store any worker related information. + +The cookie's expires header field is set to Session, which mean that after the browser is closed the cookie will be deleted. + +[HttpOnly](https://www.owasp.org/index.php/HttpOnly) is set to true (this means, it can't be read by JavaScript within the browser). + +This cookie contains the parameters: + +* _username_: username of the logged-in user (often an email) +* _sessionID_: Play's session ID +* _loginTime_: user's login time in the GUI as a timestamp +* _lastActivityTime_: user's last activity time in the GUI as a timestamp + +Additionally Play stores a hash of the whole cookie's data to check integrity of the cookie's data. + +E.g. `PLAY_SESSION:"b6c01f2fa796603491aaed94168651b54b154ca1-username=admin&sessionID=4k1atg9ugeavmegk88n41stfr4&loginTime=1524935558364&lastActivityTime=1524947602543"` diff --git a/versioned_docs/version-3.9.1/Overview/Get-started.md b/versioned_docs/version-3.9.1/Overview/Get-started.md new file mode 100644 index 0000000000..4f6a53fb9b --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/Get-started.md @@ -0,0 +1,41 @@ +--- +title: Get started +slug: /Get-started.html +sidebar_position: 5 +--- + +### Get started in 4 steps + +1. **Download JATOS and [install a local instance](Installation.html)** + +1. **Open JATOS' GUI by going to [localhost:9000](http://localhost:9000) in your browser window** + +1. **Download and import an example study** + + 1. Download one of the [Example Studies](/Example-Studies), e.g. the 'Go- / No-Go Task' with jsPsych. Do not unzip the downloaded file. + + 1. Import the study into JATOS: Go to JATOS' GUI in your browser and click on **Import Study** in the header. Choose the [_.jzip_](JATOS-Study-Archive-JZIP.html) file you just downloaded. The imported study should appear in the sidebar on the left. + +1. **Explore the GUI** + + In the sidebar click the study to get into the study's page. + + To do a test run of the entire study, click on **Run** in the toolbar on top of the page. + + If you finished running through the study, you can check the results. + + * To see whole-study results, click on the **Results** button on the top of the page. + * To see results from individual components, click on the **Results** buttons on each component's row. + + For example, you can see each result's details by clicking on the little arrow to the left of its row ([more information on how to mangage results](Manage-results.html)). + + _Here's a screenshot of a study's results view:_ + ![Results View screenshot](/img/v39x/results_view_12.png) + +### Explore + +Now it's time to explore a little bit more. + +* You can click on any component's position button and drag it to a new position within the study. +* Each component has a **Properties** button. The component's HTML file may read the data in the field 'JSON data'. This is a way to make changes in the details of the code (wording of instructions, stimuli, timing, number of trials, etc) without having to hard-code them into JavaScript. +* Where are the actual HTML, JavaScript, and CSS files? They are the files that actually run your study, so make sure you can locate them. All these files, together with any images, sound files, etc. you might have, are called "Study assets". They will be in `/path_to_my_JATOS/study_assets_root/name_of_my_study/`. \ No newline at end of file diff --git a/versioned_docs/version-3.9.1/Overview/Installation.md b/versioned_docs/version-3.9.1/Overview/Installation.md new file mode 100644 index 0000000000..2c5d2817fe --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/Installation.md @@ -0,0 +1,48 @@ +--- +title: Installation +slug: /Installation.html +sidebar_position: 3 +--- + +### Easy installation on your local computer + +**JATOS runs on MacOS, Windows and Linux** + +A local installation is straightforward. + +Usually you first develop your study with JATOS on a local computer. Then in a second step you bring it to a server installation of JATOS. + +With a local installation only you have access to JATOS - with a [server installation](Bring-your-JATOS-online.html) others can run your study via the internet too. This is especially true if you want to publish your study on Mechanical Turk. + +**For convenience JATOS is available as a bundle with Java.** + +To run JATOS, you need Java 11 installed on your computer (to be precise, you need a Java Runtime Environment, aka JRE). Chances are, you already have Java installed. To check whether Java is installed on your system, type `java -version` in your terminal (MacOS / Linux) or command window (Windows). +If you don't have Java installed, you can either download and install it (e.g. from [adoptium.net](https://adoptium.net/)) or download and install JATOS bundled with Java for your operating system. + + +### Installation Windows + +1. Download the [latest JATOS release](https://github.com/JATOS/JATOS/releases/latest) + * Without Java: *jatos.zip* + * Bundled with Java: *jatos_win_java.zip* +1. Unzip the downloaded file. You can place the unzipped folder pretty much anywhere, **except** in a folder that synchs across devices, like Dropbox or Google Drive. [Find out](Troubleshooting.html#database-is-corrupted.html) more about why not. +1. In the File Explorer move to the unzipped JATOS folder and double-click on `loader.bat`. (Or `loader` alone, if your filename extensions are hidden). A command window will open and run your local JATOS installation. Simply close this window if you want to stop JATOS. +1. All set! Now go to the browser of your choice and open [localhost:9000](http://localhost:9000). You should see the login screen (wait a moment and reload the page if you don't). Login with username 'admin' and password 'admin'. + +### Installation MacOS and Linux + +1. Download the [latest JATOS release](https://github.com/JATOS/JATOS/releases/latest) + * Without Java: *jatos.zip* + * For MacOS bundled with Java: *jatos_mac_java.zip* + * For Linux bundled with Java: *jatos_linux_java.zip* +1. Unzip the downloaded file. You can place the unzipped folder pretty much anywhere, **except** in a folder that synchs across devices, like Dropbox or Google Drive. [Find out](Troubleshooting.html#database-is-corrupted.html) more about why not. +1. In your terminal window, `cd` into the unzipped JATOS folder +1. Run the loader shell script with the command `./loader.sh start` (You might have to change the file's permissions with the command `chmod u+x loader.sh` to make it executable). Ignore pop-ups like '_To use the java command-line tool you need to install a JDK_' - just press 'OK'. +2. (On MacOS, you might see a pop-up saying that you can't open the application from an unknown developer - in that case click _Open Anyway_ within the _Privacy and Security_ tab in your _System Preferences_.) +1. All set! Now go to the browser of your choice and open [localhost:9000](http://localhost:9000). You should see the login screen (wait a moment and reload the page if you don't). Login with username 'admin' and password 'admin'. + +Your local JATOS installation will run in the background. If you want to stop it, just type `./loader.sh stop` in your terminal window. + +### How to go on from here + +The easiest way to start with JATOS is to download and import one of the [example studies](/Example-Studies) and [play around with it](Get-started.html). diff --git a/versioned_docs/version-3.9.1/Overview/JATOS-Tryout-Server.md b/versioned_docs/version-3.9.1/Overview/JATOS-Tryout-Server.md new file mode 100644 index 0000000000..0fbe1014ff --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/JATOS-Tryout-Server.md @@ -0,0 +1,15 @@ +--- +title: JATOS Tryout Server +slug: /JATOS-Tryout-Server.html +sidebar_position: 8 +--- + +Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer: + +[https://cortex.jatos.org](https://cortex.jatos.org) (log in with *test@jatos.org* and _abc1234_ or with a Google account) + +This is a normal JATOS installation with many example studies already imported (test account only). You can run the examples or import your own studies if you want to test them in a JATOS running on the Internet. + +But be aware that every day **this JATOS server will be reset** to its inital state and **all changes, uploaded experiments and data will be lost**. Additionally, there is only one log-in account that anybody can use (except you use a Google account), so everybody will be able to see, delete and take your data. In other words, **DO NOT use this JATOS instance to run your studies online**. It is only there to provide an example JATOS for people to try out. + + diff --git a/versioned_docs/version-3.9.1/Overview/Papers-Citing-JATOS.md b/versioned_docs/version-3.9.1/Overview/Papers-Citing-JATOS.md new file mode 100644 index 0000000000..7b0a20cd56 --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/Papers-Citing-JATOS.md @@ -0,0 +1,483 @@ +--- +title: Papers citing JATOS +slug: /Papers-Citing-JATOS.html +sidebar_position: 2 +--- + +JATOS has been used sucessfully to collect data all over the world. Here is a curated list of peer-reviewed publications (that we are aware of) that used JATOS to collect data. (You can also see the [full list of citations](https://scholar.google.com/scholar?oi=bibs&hl=en&cites=5951401270744316355,1084162777884423960).) + +Please [cite us](http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0130834) if you use JATOS for your research. It helps us with funding and it's great to see how we've contributed to science. + +**Please complete our short [survey](https://forms.gle/Jtjw4LxpyWVFEtG17) on how (much) you use JATOS (ca. 3 min). It’s very important for us!** + +### 2024 +Curzel, F., Osiurak, F., Trân, E., Tillmann, B. Ripollés, P., Ferreri, L. (2024) Increased pleasure positively influences prosocial behavior and memory outcomes. *iScience* [DOI](https://doi.org/10.1016/j.isci.2024.109964) + +Berkovich, R., & Meiran, N. (2024). Both pleasant and unpleasant emotional feelings follow Weber’s law but it depends how you ask. *Emotion* [DOI](https://doi.org/10.1037/emo0001343) + +Oz-Cohen, E., Berkovich, R. & Meiran, N. (2024) Bumpy ride ahead: Anticipated effort as emotional evidence?. *Cogn Affect Behav Neurosci*. [DOI](https://doi.org/10.3758/s13415-024-01194-9) + +van Moorselaar, D., & Theeuwes, J. (2024). Transfer of statistical learning between tasks. *Journal of Experimental Psychology: Human Perception and Performance*. [DOI](https://doi.org/10.1037/xhp0001216) + +Morriss, J., Lee, C.E., Wood, A. et al. (2024) Attentional bias to uncertainty-based information: a conceptual replication of Fergus et al. (2013). *Curr Psychol* [DOI](https://doi.org/10.1007/s12144-024-06067-5) + +Berry, C. J., & Shanks, D. R. (2024). Everyday amnesia: Residual memory for high confidence misses and implications for decision models of recognition. *Journal of Experimental Psychology: General* [DOI](https://doi.org/10.1037/xge0001599) + +Salava, A. Salmela, V. (2024) Diagnostic errors during perceptual learning in dermatology: a prospective cohort study of Finnish undergraduate students. *Clinical and Experimental Dermatology*. [DOI](https://doi.org/10.1093/ced/llae063) + +Béna, J., Lacassagne, D., & Corneille, O. (2024). EXPRESS: Do Uncontrolled Processes Contribute to Evaluative Learning? Insights From a New Two-US Process Dissociation Procedure and Ambivalence Measures. *Quarterly Journal of Experimental Psychology* [DOI](https://doi.org/10.1177/17470218241248138) + +Chan, Y. Y., Lee, J. C., Fam, J. P., Westbrook, R. F., & Holmes, N. M. (2024). The role of uncertainty in regulating associative change. *Journal of Experimental Psychology: Animal Learning and Cognition* [DOI](https://doi.org/10.1037/xan0000375) + +Xu, H., Armony, J.L. (2024) Arousal level and exemplar variability of emotional face and voice encoding influence expression-independent identity recognition. *Motiv Emot* [DOI](https://doi.org/10.1007/s11031-024-10066-1) + +Theeuwes, L., Snell, L., Koning, T., Bucker, B. (2024) Self-Explaining Roads: Effects of road design on speed choice *Transportation Research Part F: Traffic Psychology and Behaviour* [DOI](https://doi.org/10.1016/j.trf.2024.03.007) + +Sulpizio, S., Spinelli, G. & Scaltritti, M. (2024) Semantic Stroop interference is modulated by the availability of executive resources: Insights from delta-plot analyses and cognitive load manipulation. *Mem Cogn*. [DOi](https://doi.org/10.3758/s13421-024-01552-5) + +Liapi, A., Silva, S., Folia, V. (2024) Duration Perception and Reading in Typically Developing Adults and Adults with Developmental Dyslexia: Implications for Assessment and Intervention. *Eur. J. Investig. Health Psychol. Educ.* [DOI](https://doi.org/10.3390/ejihpe14030046) + +Sidhu, A., Uiga, L., Langley, B. et al. (2024) Reduced influence of perceptual context in mild traumatic brain injury is not an illusion. *Sci Rep* [DOI](https://doi.org/10.1038/s41598-024-56713-y) + +Smith, A.J., Bisby, J.A., Dercon, Q. et al. (2024) Hot metacognition: poorer metacognitive efficiency following acute but not traumatic stress. *Transl Psychiatry* [DOI](https://doi.org/10.1038/s41398-024-02840-z) + +Grignolio, D., Acunzo, D. J., & Hickey, C. (2024). Object-based attention is accentuated by object reward association. *Journal of Experimental Psychology: Human Perception and Performance* [DOI](https://doi.org/10.1037/xhp0001177) + +Vainre M, Dalgleish T, Watson P, et al Work Engagement and Well-being Study (SWELL): a randomised controlled feasibility trial evaluating the effects of mindfulness versus light physical exercise at work. *BMJ Ment Health*. [DOI](https://doi.org/10.1136/bmjment-2023-300885) + +Nguyen, N., Lancia, L., Huttner, L., Schwartz, J., & Diard, J. (2024). Listeners' convergence towards an artificial agent in a joint phoneme categorization task. *Glossa Psycholinguistics*. [DOI](http://dx.doi.org/10.5070/G6011165) + +Theeuwes, J., Huang, C., Frings, C., & van Moorselaar, D. (2024). Statistical learning of motor preparation. *Journal of Experimental Psychology: Human Perception and Performance*. [DOI](https://doi.org/10.1037/xhp0001174) + +Corradi G, Aguilar P, Aguiar F, Olivera-La Rosa A (2024) Age and moral disgust: An experimental priming effects vignette study. *PLoS ONE* [DOI](https://doi.org/10.1371/journal.pone.0295039) + +Del Popolo Cristaldi F., Buodo G., Gambarota F., Oosterwijk S., Mento G. (2024) How previous experience shapes future affective subjective ratings: A follow-up study investigating implicit learning and cue ambiguity. *PLoS ONE* [DOI](https://doi.org/10.1371/journal.pone.0297954) + +Bognar, M., Szekely, Z., Varga, M.A. et al. (2024 )Cognitive control adjustments are dependent on the level of conflict. *Sci Rep* [DOI](https://doi.org/10.1038/s41598-024-53090-4) + +van Moorselaar D, Theeuwes J. (2024) Spatial transfer of object-based statistical learning. *Atten Percept Psychophys* [DOI](http://doi.org/10.3758/s13414-024-02852-3) + +Lallement, C., Lemaire, P. (2024) Are There Age-Related Differences in Effects of Positive and Negative Emotions in Arithmetic? *Experimental Psychology* [DOI](https://doi.org/10.1027/1618-3169/a000595) + +Vandendaele, A., Prutean, N. and Declerck, M. (2024). A Blessing in Disguise: Flanking Words Can Cancel Language Switch Costs. *Journal of Cognition* [DOI](https://doi.org/10.5334/joc.332) + +Moore, C.M., Zheng, Q. (2024) Limited midlevel mediation of visual crowding: Surface completion fails to support uncrowding. *Journal of Vision* [DOI](https://doi.org/10.1167/jov.24.1.11) + +Oppenheim, G.M., Nozari, N. (2024) Similarity-induced interference or facilitation in language production reflects representation, not selection. *Cognition* [DOI](https://doi.org/10.1016/j.cognition.2024.105720) + +Soto, D., Salazar, A., Elosegi, P. et al. (2024) A novel image database for social concepts reveals preference biases in autistic spectrum in adults and children. *Psychon Bull Rev* [DOI](https://doi.org/10.3758/s13423-023-02443-7) + +Martin, C.D., Pastureau, R., Kerr, E. and de Bruin, A. (2024) Processing of Synonyms and Homographs in Bilingual and Monolingual Speakers. *Journal of Cognition* [DOI](https://doi.org/10.5334/joc.329) + +Grootswagers T, Robinson AK, Shatek SM, Carlson TA (2024) Mapping the dynamics of visual feature coding: Insights into perception and integration. *PLoS Comput Biol* [DOI](https://doi.org/10.1371/journal.pcbi.1011760) + +Garre-Frutos, F., Vadillo, M.A., González, F. et al. (2024) On the reliability of value-modulated attentional capture: An online replication and multiverse analysis. *Behav Res*. [DOI](https://doi.org/10.3758/s13428-023-02329-5) + +Mu, Y., Schubö, A. & Tünnermann, J. (2024) Adapting attentional control settings in a shape-changing environment. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-023-02818-x) + +Shyr, M.C., Joshi, S.S. (2024) A Case Study of the Validity of Web-based Visuomotor Rotation Experiments. *J Cogn Neurosci* [DOI](https://doi.org/10.1162/jocn_a_02080) + +### 2023 +Yang, W., and Rauwolf, P., Frances, C., Wei, Y., Molina-Nieto, O., Duñabeitia, J.A., Thierry, G. (2023) Evidence for Strategic Language Use in Chinese-English Bilinguals. *SSRN* [DOI](http://dx.doi.org/10.2139/ssrn.4396191) + + +Berkovich, R., & Meiran, N. (2023). Pleasant emotional feelings follow one of the most basic psychophysical laws (weber’s law) as most sensations do. *Emotion* [DOI](https://doi.org/10.1037/emo0001161) + +Del Popolo Cristaldi, F., Gambarota, F., & Oosterwijk, S. (2023). Does your past define you? The role of previous visual experience in subjective reactions to new affective pictures and sounds. *Emotion* [DOI](https://doi.org/10.1037/emo0001168) + +Barnes, L., Rangelov, D., Mattingley, J. B., & Woolgar, A. (2023). Fractionating distraction: How past- and future-relevant distractors influence integrated decisions. *Journal of Experimental Psychology: Human Perception and Performance*. [DOI](https://doi.org/10.1037/xhp0001081) + +Modirrousta-Galian, A., Higham, P. A., & Seabrooke, T. (2023). Effects of inductive learning and gamification on news veracity discernment. *Journal of Experimental Psychology: Applied*. [DOI](https://doi.org/10.1037/xap0000458) + +Curzel, F., Carraturo, G., Ripollés, P., & Ferreri, L. (2023). Better off alone? When sharing music reduces pleasure responses. *Advances in Cognitive Psychology*. [DOI](https://doi.org/10.5709/acp-0400-6) + +Fahnenstich, H., Rieger, T., Roesler, E. (2023). Trusting under risk – comparing human to AI decision support agents. *Computers in Human Behavior* [DOI](https://doi.org/10.1016/j.chb.2023.108107) + +Smith, H. J., Gilbert, R. A., & Davis, M. H. (2023). Can speech perception deficits cause phonological impairments? Evidence from short-term memory for ambiguous speech. *Journal of Experimental Psychology: General* [DOI](https://doi.org/10.1037/xge0001522) + +Godwin, H.J., Hout, M.C. (2023) Just say ‘I don’t know’: Understanding information stagnation during a highly ambiguous visual search task. *PLoS ONE*. [DOI](https://doi.org/10.1371/journal.pone.0295669) + +Palmer, C. J., Kim, P., & Clifford, C. W. G. (2023). Gaze behavior as a visual cue to animacy. *Journal of Experimental Psychology: General*. [DOI](https://doi.org/10.1037/xge0001281) + +Gurunandan, K., Cooper, E., Tibon, R., Henson, R.N., & Greve, A. (2023) No evidence of fast mapping in healthy adults using an implicit memory measure: failures to replicate the lexical competition results of Coutanche and Thompson-Schill (2014). *Memory*. [DOI](https://doi.org/10.1080/09658211.2023.2262188) + +Hsieh, J.Y.J., Boyce, W.P., Goddard, E. et al. (2023) Colour information biases facial age estimation and reduces inter-observer variability. *Sci Rep*. [DOI](https://doi.org/10.1038/s41598-023-39902-z) + +Wang, X., Li, X., Yin, Z., Wu, Y., & Liu, J. (2023). Emotional intelligence of Large Language Models. *Journal of Pacific Rim Psychology*. [DOI](https://doi.org/10.1177/18344909231213958) + +Marks, R.A., Eggleston, R., Kovelman, I. (2023) Brain bases of morphological awareness and longitudinal word reading outcomes. *Journal of Experimental Child Psychology*. [DOI](https://doi.org/10.1016/j.jecp.2023.105802) + +Magnabosco, F., Hauk, O. (2023) An eye on semantics: a study on the influence of concreteness and predictability on early fixation durations. *Language, Cognition and Neuroscience*. [DOI](www.doi.org/10.1080/23273798.2023.2274558) + +Oberholzer, Y., Olschewski, S., Scheibehenne, B. Complexity Aversion in Risky Choices and Valuations: Moderators and Possible Causes. *Journal of Economic Psychology*. [DOI](https://doi.org/10.1016/j.joep.2023.102681). + +Loaiza, V.M., Cheung, H.W. & Goldenhaus-Manning, D.T. (2023) What you don’t know can’t hurt you: Retro-cues benefit working memory regardless of prior knowledge in long-term memory. *Psychon Bull Rev*. [DOI](https://doi.org/10.3758/s13423-023-02408-w) + +Everhardt, M.K., Sarampalis, A., Coler, M., Başkent, D. Lowie, W. (2023) Prosodic Focus Interpretation in Spectrotemporally Degraded Speech by Non-Native Listeners. *Journal of Speech, Language, and Hearing Research* [DOI](https://doi.org/10.1044/2023_JSLHR-22-00568) + +Schreiner, M. R., Bröder, A., & Meiser, T. (2023). Agency effects on the binding of event elements in episodic memory. *Quarterly Journal of Experimental Psychology* [DOI](https://doi.org/10.1177/17470218231203951) + +Rieger, T., Manzey, D., Meussling, B., Onnasch, L., Roesler, E. (2023) Be careful what you explain: Benefits and costs of explainable AI in a simulated medical task. *Computers in Human Behavior: Artificial Humans*. [DOI](https://doi.org/10.1016/j.chbah.2023.100021) + +Peterson, L.M., Susilo, T., Clifford, C.G.W., Palmer, C.J. (2023) Discrimination of facial identity based on simple contrast patterns generated by shading and shadows. *Vision Research*. [DOI](https://doi.org/10.1016/j.visres.2023.108307) + +Peterson, L.M., Clifford, C.W.G., Palmer, C.J. (2023) Detection of Mooney faces is robust to image asymmetries produced by illumination. *Journal of Vision* [DOI](https://doi.org/10.1167/jov.23.12.9) + +Gemignani, M., Giannotti, M., Rigo, P., de Falco, S. (2023) Attentional bias to infant faces might be associated with previous care experiences and involvement in childcare in same-sex mothers. *International Journal of Clinical and Health Psychology* [DOI](https://doi.org/10.1016/j.ijchp.2023.100419) + +Schreiner, M.R., Hütter, M. (2023) The Influence of Social Status on Memory: No Evidence for Effects of Social Status on Event Element Binding. *Social Cognition* [DOI](https://doi.org/10.1521/soco.2023.41.5.447) + +Vandendaele, A., & Grainger, J. (2023). Lexical competition in the flankers task revised. *PLoS one* [DOI](https://doi.org/10.1371/journal.pone.0285292) + +Labaronne, M., Ferreri, L. & Plancher, G. (2023) How do intentions modulate the effect of working memory on long-term memory? *Psychon Bull Rev*. [DOI](https://doi.org/10.3758/s13423-023-02381-4) + +Béna, J., Rouard, M., & Corneille, O. (2023). You won't believe it! Truth judgments for clickbait headlines benefit (but less so) from prior exposure. *Applied Cognitive Psychology* [DOI](https://doi.org/10.1002/acp.4134) + +Constant, M., Pereira, M., Faivre, N. et al. (2023) Prior information differentially affects discrimination decisions and subjective confidence reports. *Nat Commun*. [DOI](https://doi.org/10.1038/s41467-023-41112-0) + +Jost, L., & Jansen, P. (2023). EXPRESS: The Influence of the Design of Mental Rotation Trials on Performance and Possible Differences Between Sexes: A Theoretical Review and Experimental Investigation. *Quarterly Journal of Experimental Psychology*. [DOI](https://doi.org/10.1177/17470218231200127) + +Rieger, T., Kugler, L., Manzey, D., & Roesler, E. (2023). The (Im)perfect Automation Schema: Who Is Trusted More, Automated or Human Decision Support? *Human Factors*. [DOI](https://doi.org/10.1177/00187208231197347) + +Everhardt, M.K., Sarampalis, A., Coler, M., Başkent, D., & Lowie, W. (2023). Prosodic Focus Interpretation in Spectrotemporally Degraded Speech by Non-Native Listeners. *Journal of Speech, Language, and Hearing Research. [DOI](https://doi.org/10.1044/2023_JSLHR-22-00568) + +Vieth, E., von Stockhausen, L. (2023) Effects of short mindful breathing meditations on executive functioning in two randomized controlled double-blinded experiments. *Acta Psychologica* [DOI](https://doi.org/10.1016/j.actpsy.2023.104006) + +Sobczak, A., Bunzeck, N. (2023) Effects of positive and negative social feedback on motivation, evaluative learning, and socio-emotional processing. *npj Sci. Learn.* [DOI](https://doi.org/10.1038/s41539-023-00178-7) + +Coy, N., Bendixen, A., Grimm, S. et al. (2023) Deviants violating higher-order auditory regularities can become predictive and facilitate behaviour. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-023-02763-9) + +Ivanov, Y., Theeuwes, J. & Bogaerts, L. (2023) Reliability of individual differences in distractor suppression driven by statistical learning. *Behav Res*. [DOI](https://doi.org/10.3758/s13428-023-02157-7) + +Wang-Ly, Nathan and Newell, Ben R. (2023) Uncertain goals and savings adequacy: Contrasting economic and psychological perspectives. *SSRN* [DOI](http://dx.doi.org/10.2139/ssrn.4511291) + +Putra, K.A., Prasetio C.E., & Sianipar, A. (2023) Inhibition on irrelevant negative information alleviates the mediating role of psychological distress in the association between trait rumination and symptoms of depression and anxiety. *Cogent Psychology* [DOI](http://doi.org/10.1080/23311908.2023.2228556) + +de Waard, J., van Moorselaar, D., Bogaerts, L. et al. (2023) Statistical learning of distractor locations is dependent on task context. *Sci Rep* [DOI](https://doi.org/10.1038/s41598-023-38261-z) + +Prasetio, C.E., Putri, V.M. and Sianipar, A. (2023), The Moderating Role of Inhibition on Irrelevant Emotional Information in the Relation of Cognitive Reappraisal and Affect Balance: Evidence from a Negative Affective Priming Task. *Jpn Psychol Res.* [DOI](https://doi.org/10.1111/jpr.12465) + +Jansen, P., Rahe, M., Hoja, S. et al. (2023) Are Character Strengths and Attitudes towards Vegetarian Food Related? *Int J Appl Posit Psychol*. [DOI](https://doi.org/10.1007/s41042-023-00104-7) + +Kahan, T.A., Smith, Z.P. (2023) Effects of alerting signals on the spatial Stroop effect: evidence for modality differences. *Psychological Research*. [DOI](https://doi.org/10.1007/s00426-023-01846-4) + +Liao, MR., Grindell, J.D. & Anderson, B.A. (2023) A comparison of mental imagery and perceptual cueing across domains of attention. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-023-02747-9) + +Büsel, C., Seiz, C. M., Hoffmann, A., Sachse, P., & Ansorge, U. (2023). EXPRESS: Swift Attenuation of Irrelevant Features Through Feature Consistency – Evidence From a Capture-Probe Version of the Contingent-Capture Protocol. *Quarterly Journal of Experimental Psychology* [DOI](https://doi.org/10.1177/17470218231186045) + +Xie, T., Fu, S. & Mento, G. (2023) Faces do not guide attention in an object-based facilitation manner. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-023-02742-0) + +Ziereis, A., Schacht, A. (2023) Motivated attention and task relevance in the processing of cross-modally associated faces: Behavioral and electrophysiological evidence. *Cogn Affect Behav Neurosci*. [DOI](https://doi.org/10.3758/s13415-023-01112-5) + +Winkelmair, A., Siebertz, M., Jost, L. et al. (203) Explicit and Implicit Affective Attitudes toward Sustainability: The Role of Mindfulness, Heartfulness, Connectedness to Nature and Prosocialness. *Int J Appl Posit Psychol* [DOI](https://doi.org/10.1007/s41042-023-00107-4) + +Mazor, M., Maimon-Mor, R.O., Charles, L. et al. (2023) Paradoxical evidence weighting in confidence judgments for detection and discrimination. *Atten Percept Psychophys.* [DOI](https://doi.org/10.3758/s13414-023-02710-8) + +Thoma, D., Becker, K., & Kißler, A. (2023). Presuppositions are more persuasive than assertions if addressees accommodate them: Experimental evidence for philosophical reasoning. *Applied Psycholinguistics*. [DOI](https://doi.org/10.1017/S0142716423000292) + +Rullo, M., Presaghi, F., Baldner, C., Livi, S., & Butera, F. (2023). Omertà in intragroup cheating: The role of ingroup identity in dishonesty and whistleblowing. Group Processes & Intergroup Relations. [DOI](https://doi.org/10.1177/13684302231164722) + +Hasenäcker, J., & Domahs, F. (2023). Prosody affects visual perception in polysyllabic words: Evidence from a letter search task. *Quarterly Journal of Experimental Psychology*. [DOI](https://doi.org/10.1177/17470218231176691) + +Fenn J., Helm J.F., Höfele P., Kulbe L., Ernst A., Kiesel A. (2023) Identifying key-psychological factors influencing the acceptance of yet emerging technologies–A multi-method-approach to inform climate policy. *PLOS Clim* [DOI](https://doi.org/10.1371/journal.pclm.0000207) + +Gao, Y., de Waard, J. & Theeuwes, J. (2023) Learning to suppress a location is configuration-dependent. *Atten Percept Psychophys* [DOI](https://doi.org/10.3758/s13414-023-02732-2) + +Homann, L.A., Drody, A.C. & Smilek, D. (2023) The effects of self-selected background music and task difficulty on task engagement and performance in a visual vigilance task. *Psychological Research* [DOI](https://doi.org/10.1007/s00426-023-01836-6) + +Ng, D. W., Lee, J. C., & Lovibond, P. F. (2023). Unidirectional rating scales overestimate the illusory causation phenomenon. *Quarterly Journal of Experimental Psychology* [DOI](https://doi.org/10.1177/17470218231175003) + +Arslan, B., Ng, F., Göksun, T., & Nozari, N. (2023). Trust my gesture or my word: How do listeners choose the information channel during communication? *Journal of Experimental Psychology: Learning, Memory, and Cognition* [DOI](https://doi.org/10.1037/xlm0001253) + +Fromm, S.P., Wieland, L., Klettke, A., Nassar, M.R., Katthagen, T., Markett, S., Heinz, A., Schlagenhauf, F. (2023) Computational mechanisms of belief updating in relation to psychotic-like experiences. *Front. Psychiatry* [DOI](https://doi.org/10.3389/fpsyt.2023.1170168) + +Comay, N.A., Della Bella, G., Lamberti, P., Sigman, M. Solovey, G., Barttfeld, P. (2023) The presence of irrelevant alternatives paradoxically increases confidence in perceptual decisions. *Cognition* [DOI](https://doi.org/10.1016/j.cognition.2023.105377) + +Tian, J., Ren, K., Gunderson, EA. (2023) Verbal labels influence children's processing of decimal magnitudes. *Journal of Applied Developmental Psychology* [DOI](https://doi.org/10.1016/j.appdev.2023.101537) + +Bognar, M., Gyurkovics, M., van Steenbergen, H. & Aczel, B. (2023) Phasic affective signals by themselves do not regulate cognitive control. *Cognition and Emotion* [DOI](https://doi.org/10.1080/02699931.2023.2191172) + +Huang, C., Donk, M. & Theeuwes, J. (2023) Attentional suppression is in place before display onset. Atten Percept Psychophys. [DOI](https://doi.org/10.3758/s13414-023-02704-6) + +Salava, A, Salmela, V. (2023) Perceptual learning in dermatology—A Finnish cohort study of undergraduate medical students. *J Eur Acad Dermatol Venereol.* [DOI](https://doi.org/10.1111/jdv.19058) + +Béna, J., Mierop, A., Bancu, D. Unkelbach, C., Corneille, O. The Role of Valence Matching in the Truth-by-Repetition Effect. *Social Cognition* [DOI](http://dx.doi.org/10.1521/soco.2023.41.2.193) + +Embon, I., Cukier, S., Iorio, A., Barttfeld, P., Solovey, G. Is visual metacognition associated with autistic traits? A regression analysis shows no link between visual metacognition and Autism-Spectrum Quotient scores. *Consciousness and Cognition* [DOI](https://doi.org/10.1016/j.concog.2023.103502) + +Yan, N., Grindell, J., & Anderson, B. A. (2023). Encoding history enhances working memory encoding: Evidence from attribute amnesia. *Journal of Experimental Psychology: Human Perception and Performance* [DOI](https://doi.org/10.1037/xhp0001096) + +Dijkstra, N., Fleming, S.M. (2023) Subjective signal strength distinguishes reality from imagination. *Nat Commun* [DOI](https://doi.org/10.1038/s41467-023-37322-1) + +Guseva, M., Bogler, C., Allefeld C., Haynes JD. (2023) Instruction effects on randomness in sequence generation. *Frontiers in Psychology*. [DOI](https://doi.org/10.3389/fpsyg.2023.1113654) + +van Moorselaar, D., & Theeuwes, J. (2023). Statistical Learning Within Objects. *Psychological Science* [DOI](https://doi.org/10.1177/09567976231154804) + +Lu, Z., van Zoest, W. (2023) Combining social cues in attention: Looking at gaze, head, and pointing cues. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-023-02669-6) + +Del Popolo Cristaldi F, Toffoli L, Duma GM, Mento G (2023) Little fast, little slow, should I stay or should I go? Adapting cognitive control to local-global temporal prediction across typical development. *PLoS ONE* [DOI](https://doi.org/10.1371/journal.pone.0281417) + +Li, AS., Bogaerts, L. & Theeuwes, J. (2023) No evidence for spatial suppression due to across-trial distractor learning in visual search. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-023-02667-8) + +Reichardt, R., Polner, B., & Simor, P. (2023). Influencing prior knowledge through a short reading impacts curiosity and learning. *Applied Cognitive Psychology* [DOI](https://doi.org/10.1002/acp.4047) + +Guediche, S., Navarra-Barindelli, E., Martin, C.D. (2023). Noise Modulates Crosslinguistic Effects on Second-Language Auditory Word Recognition. *Journal of speech, language, and hearing research* [DOI](https://doi.org/10.1044/2022_JSLHR-22-00368) + +Goldenhaus-Manning, D.T., Cooper, N.R. & Loaiza, V.M. (2023) Examining the role of attention during feature binding in visuospatial working memory. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-023-02655-y) + +Stark C.E.L., Noche J.A., Ebersberger J.R., Mayer L., Stark S.M. (2023) Optimizing the mnemonic similarity task for efficient, widespread use. *Frontiers in Behavioral Neuroscience* [DOI](https://doi.org/10.3389/fnbeh.2023.1080366) + +Lee, M.D., Stark, C.E.L. (2023) Bayesian modeling of the Mnemonic Similarity Task using multinomial processing trees. *Behaviormetrika* [DOI](https://doi.org/10.1007/s41237-023-00193-3) + +Kessler, Y., Zilberman, N., & Kvitelashvili, S. (2023). Updating, Fast and Slow: Items, but Not Item-Context Bindings, are Quickly Updated Into Working Memory as Part of Response Selection. *Journal of Cognition* [DOI](http://doi.org/10.5334/joc.257) + +Jevtović, M., Antzaka, A., & Martin, C. D. (2023). Déjà-lu: When Orthographic Representations are Generated in the Absence of Orthography. *Journal of Cognition* [DOI](http://doi.org/10.5334/joc.250) + +Archer-Boyd, A.W., Harland, A., Goehring, T., Carlyon, RP. (2023) An online implementation of a measure of spectro-temporal processing by cochlear-implant listeners. *JASA Express Letters* [DOI](https://doi.org/10.1121/10.0016838) + +Zoefel B, Gilbert RA, Davis MH (2023) Intelligibility improves perception of timing changes in speech. *PLoS ONE* [DOI](https://doi.org/10.1371/journal.pone.0279024) + +Wainio-Theberge, S., Armony, J.L. (2023) Antisocial and impulsive personality traits are linked to individual differences in somatosensory maps of emotion. *Sci Rep* [DOI](https://doi.org/10.1038/s41598-023-27880-1) + +Labaronne, M., Jarjat, G., & Plancher, G. (2023). Attentional Refreshing in the Absence of Long-Term Memory Content: Role of Short-Term and Long-Term Consolidation. *Journal of Cognition*. [DOI](http://doi.org/10.5334/joc.246) + +Jensen, A., Thériault, L., Yilmaz, E., Pon, E., Davidson, PSR. (2023) Mental rotation, episodic memory, and executive control: Possible effects of biological sex and oral contraceptive use. *Neurobiology of Learning and Memory* [DOI](https://doi.org/10.1016/j.nlm.2023.107720) + +### 2022 +Lee, J. C., Le Pelley, M. E., & Lovibond, P. F. (2022). Nonreactive testing: Evaluating the effect of withholding feedback in predictive learning. *Journal of Experimental Psychology: Animal Learning and Cognition* [DOI](https://doi.org/10.1037/xan0000311) + +Kim, A. J., Lee, D. S., Grindell, J. D., & Anderson, B. A. (2022). Selection history and the strategic control of attention. *Journal of Experimental Psychology: Learning, Memory, and Cognition* [DOI](https://doi.org/10.1037/xlm0001194) + +Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. *Atten Percept Psychophys* [DOI](https://doi.org/10.3758/s13414-022-02473-8) + +Gemignani, M., Giannotti, M., Schmalz, X., Rigo, P., & De Falco, S. (2022). Attentional Prioritization of Infant Faces in Parents: The Influence of Parents’ Experiences of Care. *International Journal of Environmental Research and Public Health*. [DOI](http://dx.doi.org/10.3390/ijerph20010527) + +Barnes, S., Prescott, J. and Adams, J. (2022), Initial evaluation of a mobile therapeutic game for adolescent anxiety disorders. *Mental Health and Social Inclusion* [DOI](https://doi.org/10.1108/MHSI-11-2022-0076) + +Roesler*, E., Rieger*, T., & Manzey, D. (2022). Trust towards Human vs. Automated Agents: Using a Multidimensional Trust Questionnaire to Assess The Role of Performance, Utility, Purpose, and Transparency. *Proceedings of the Human Factors and Ergonomics Society Annual Meeting* [DOI](https://doi.org/10.1177/107118132266106) + +Schroter, FA., Siebertz, M., Hofmann, P., (2022) Jansen, P. Psychological and socio-demographic factors in the pre-decision stage for the purchase of e-cars. *Current Research in Ecological and Social Psychology* [DOI](https://doi.org/10.1016/j.cresp.2022.100072) + +Béna, J., Mauclet, A., & Corneille, O. (2022). Does co-occurrence information influence evaluations beyond relational meaning? An investigation using self-reported and mouse-tracking measures of attitudinal ambivalence. *Journal of Experimental Psychology: General.* [DOI](https://doi.org/10.1037/xge0001308) + +Johnson, S.T., Most, S.B.(2022) Taking the path of least resistance now, but not later: Pushing cognitive effort into the future reduces effort discounting. *Psychon Bull Rev*. [DOI](https://doi.org/10.3758/s13423-022-02198-7) + +Dahm, S.F.; Muraki, E.J.; Pexman, P.M. (2022) Hand and Foot Selection in Mental Body Rotations Involves Motor-Cognitive Interactions. *Brain Sci.* [DOI](https://doi.org/10.3390/brainsci12111500) + +da Fonseca, M., Maffei, G., Moreno-Bote, R. et al. (2022) Mood and implicit confidence independently fluctuate at different time scales. *Cogn Affect Behav Neurosci*. [DOI](https://doi.org/10.3758/s13415-022-01038-4) + +Wittmann BC, Şatırer Y. (2022) Decreased associative processing and memory confidence in aphantasia. *Learn Mem.* [DOI](https://doi.org/10.1101/lm.053610.122) + +Muhmenthaler, MC, Meier, B. (2022) Attentional attenuation (rather than attentional boost) through task switching leads to a selective long-term memory decline. *Frontiers in Psychology* [DOI](https://doi.org/10.3389/fpsyg.2022.1027871) + +Mueckstein, M., Heinzel, S., Granacher, U., Brahms, M., Rapp, MA., Stelzel, C. (2022) Modality-specific effects of mental fatigue in multitasking, *Acta Psychologica* [DOI](https://doi.org/10.1016/j.actpsy.2022.103766) + +Béna, J., Corneille, O., Mierop, A., & Unkelbach, C. (2022). Robustness Tests Replicate Corneille et al.’s (2020) Fake News by Repetition Effect. *International Review of Social Psychology* [DOI](http://doi.org/10.5334/irsp.683) + +Diana, F., Kawahara, M., Saccardi, I. et al. (2022) A Cross-Cultural Comparison on Implicit and Explicit Attitudes Towards Artificial Agents. *Int J of Soc Robotics*. [DOI](https://doi.org/10.1007/s12369-022-00917-7) + +Kessler, Y., Rozanis, M. (2022) Task cues are quickly updated into working memory as part of their processing: The multiple-cue task-switching paradigm. *Psychon Bull Rev*. [DOI](https://doi.org/10.3758/s13423-022-02186-x) + +Radović T, Rieger T and Manzey D (2022) A global and local perspective of interruption frequency in a visual search task. *Front. Psychol.* [DOI](https://doi.org/10.3389/fpsyg.2022.951048) + +Vos, M., Minor, S., & Ramchand, G. C. (2022). Comparing infrared and webcam eye tracking in the Visual World Paradigm. *Glossa Psycholinguistics* [DOI](http://dx.doi.org/10.5070/G6011131) + +Tsang, K. Y., & Mannion, D. J. (2022). Relating Sound and Sight in Simulated Environments. M*ultisensory Research* [DOI](https://doi.org/10.1163/22134808-bja10082) + +Kahan TA, Slowiaczek LM, Harrison AC, Bogue CM. (2022) Temporal and sequential negative priming generalise across visual and auditory modalities and are dependent on relative rather than absolute speed. *Quarterly Journal of Experimental Psychology* [DOI](https://doi.org/10.1177/17470218221100248) + +Coy N., Bendixen, A., Grimm, S., Roeber, U., & Schröger, E. (2022) Is the Oddball Just an Odd-One-Out? The Predictive Value of Rule-Violating Events *Auditory Perception & Cognition* [DOI](https://doi.org/10.1080/25742442.2022.2094657) + +Yildirim, B., Kurdoglu-Ersoy P., Kapucu A., & Tekozel, M. (2022) Is there an infidelity-based reproductive processing advantage in adaptive memory? Effects of survival processing and jealousy processing on recall performance. *Journal of Cognitive Psychology* [DOI](https://doi.org/10.1080/20445911.2022.2090948) + +Del Popolo Cristaldi, F., Granziol, U., Bariletti, I., Mento, G. (2022) Doing Experimental Psychological Research from Remote: How Alerting Differently Impacts Online vs. Lab Setting. *Brain Sci.* [DOI](https://doi.org/10.3390/brainsci12081061) + +Contemori, G., Saccani, MS., Bonato, M. (2022) Multitasking Effects on Perception and Memory in Older Adults. *Vision* [DOI](https://doi.org/10.3390/vision6030048) + +Daoultzis, KC., & Kordoutis, P. (2022) A Pilot Study Testing A New Visual Stimuli Database for Probing Men’s Gender Role Conflict: GRASP (Gender Role Affective Stimuli Pool) *Journal of Homosexuality* [DOI](https://doi.org/10.1080/00918369.2022.2104147) + +Chen, X., Hartsuiker, RJ., Muylle, M., Slim, MS., Zhang, C. (2022) The effect of animacy on structural Priming: A replication of Bock, Loebell and Morey (1992) *Journal of Memory and Language* [DOI](https://doi.org/10.1016/j.jml.2022.104354) + +Witek, M., Kwiecień, S. Włodarczyk, M., Wrzosek, M., Bondek, J. (2022) Prosody in recognizing dialogue-specific functions of speech acts. Evidence from Polish. +*Language Sciences* [DOI](https://doi.org/10.1016/j.langsci.2022.101499) + +Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. *Languages* [DOI](https://doi.org/10.3390/languages7030197) + +Norden M, Hofmann A, Meier M, Balzer F, Wolf O, Böttinger E, Drimalla H. (2022) Inducing and Recording Acute Stress Responses on a Large Scale With the Digital Stress Test (DST): Development and Evaluation Study. *J Med Internet Res* [DOI](https://www.jmir.org/2022/7/e32280) + +Henke, L., Guseva, M., Wagemans, K. et al. (2022) Surgical face masks do not impair the decoding of facial expressions of negative affect more severely in older than in younger adults. *Cogn. Research*. [DOI](https://doi.org/10.1186/s41235-022-00403-8) + +Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. *Human Factors*. [DOI](https://doi.org/10.1177/00187208221111236) + +Schreiner MR, Meiser T, Bröder A. (2022) The binding structure of event elements in episodic memory and the role of animacy. *Quarterly Journal of Experimental Psychology* [DOI](https://doi.org/10.1177/17470218221096148) + +Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. *Clin Exp Dermatol.* [DOI](https://doi.org/10.1111/ced.15201) + +Reichardt, R., Polner, B. & Simor, P. (2022) The graded novelty encoding task: Novelty gradually improves recognition of visual stimuli under incidental learning conditions. *Behav Res* [DOI](https://doi.org/10.3758/s13428-022-01891-8) + +Lovibond, P. F., Chow, J. Y. L., Tobler, C., & Lee, J. C. (2022). Reversal of inhibition by no-modulation training but not by extinction in human causal learning. *Journal of Experimental Psychology: Animal Learning and Cognition* Advance online publication. [DOI](https://doi.org/10.1037/xan0000328) + +Donato R, Pavan A, Cavallin G, Ballan L, Betteto L, Nucci M, Campana G. (2022) Mechanisms Underlying Directional Motion Processing and Form-Motion Integration Assessed with Visual Perceptual Learning. *Vision* [DOI](https://doi.org/10.3390/vision6020029) + +Appelganc K, Rieger T, Roesler E, Manzey D. (2022) How Much Reliability Is Enough? A Context-Specific View on Human Interaction With (Artificial) Agents From Different Perspectives. *Journal of Cognitive Engineering and Decision Making* [DOI](https://doi.org/doi:10.1177/15553434221104615) + +Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns *Auditory Perception & Cognition* [DOI](http://doi.org/10.1080/25742442.2022.2082827) + +Rosi, V., Houix, O. Misdariis, N., Susini, P. (2022) Investigating the Shared Meaning of Metaphorical Sound Attributes: Bright, Warm, Round, and Rough. *Music Perception* [DOI](https://doi.org/10.1525/mp.2022.39.5.468) + +Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. *Consciousness and Cognition* [DOI](https://doi.org/10.1016/j.concog.2022.103350) + +Everhardt, M., Sarampalis, A., Coler, M., Baskent, D., Lowie, W. (2022) Interpretation of prosodically marked focus in cochlear implant-simulated speech by non-native listeners. *Proc. Speech Prosody*. [DOI](https://doi.org/10.21437/SpeechProsody.2022-15) + +Palmer, C.J., Goddard, E., Clifford, C.W.G. (2022) Face detection from patterns of shading and shadows: The role of overhead illumination in generating the familiar appearance of the human face. *Cognition* [DOI](https://doi.org/10.1016/j.cognition.2022.105172) + +Frances, C., Navarra-Barindelli E., Martin C.D. (2022) Speaker Accent Modulates the Effects of Orthographic and Phonological Similarity on Auditory Processing by Learners of English. *Frontiers in Psychology* [DOI](https://doi.org/10.3389/fpsyg.2022.892822) + +Ciston, A.B., Forster, C. Brick, TR.,Kühn, S., Verrel, J., Filevich, E. (2022) Do I look like I'm sure?: Partial metacognitive access to the low-level aspects of one's own facial expressions. *Cognition* [DOI](https://doi.org/10.1016/j.cognition.2022.105155) + +Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" *Open Psychology* [DOI](https://doi.org/10.1515/psych-2022-0003) + +Lauren A. Homann, Brady R. T. Roberts, Sara Ahmed & Myra A. Fernandes (2022) Are emojis processed visuo-spatially or verbally? Evidence for dual codes *Visual Cognition* [DOI](https://doi.org/10.1080/13506285.2022.2050871) + +Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities *Journal of Pragmatics* [DOI](https://doi.org/10.1016/j.pragma.2022.03.011) + +Vainre M, Galante J, Watson P, et al (2022). Protocol for the Work Engagement and Well-being Study (SWELL): a randomised controlled feasibility trial evaluating the effects of mindfulness versus light physical exercise at work. *BMJ Open*; [DOI](https://doi.org/10.1136/bmjopen-2021-050951) + +Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. *Atten Percept Psychophys*. [DOI](https://doi.org/10.3758/s13414-022-02473-8) + +Scholl J, Trier HA, Rushworth MFS, Kolling N (2022) The effect of apathy and compulsivity on planning and stopping in sequential decision-making. *PLOS Biology* [DOI](https://doi.org/10.1371/journal.pbio.3001566) + +Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, *Consciousness and Cognition* [DOI](https://doi.org/10.1016/j.concog.2022.103316) + +Huang, C., Donk, M., & Theeuwes, J. (2022). Proactive enhancement and suppression elicited by statistical regularities in visual search. *Journal of Experimental Psychology: Human Perception and Performance*. [DOI](https://doi.org/10.1037/xhp0001002) + +Jevtović, M., Antzaka, A., & Martin, C. D. (2022). Gepo with a G, or Jepo with a J? Skilled Readers Generate Orthographic Expectations for Novel Spoken Words Even When Spelling is Uncertain. *Cognitive Science* [DOI](https://doi.org/10.1111/cogs.13118) + +Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) *HMD* [DOI](https://doi.org/10.1365/s40702-022-00856-x) + +Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. *Motiv Emot* (2022). [DOI](https://doi.org/10.1007/s11031-022-09932-7) + +Quent JA, Henson RN. Novel immersive virtual reality experiences do not produce retroactive memory benefits for unrelated material. (2022) *Quarterly Journal of Experimental Psychology*. [DOI](http://dx.doi.org/10.1177/17470218221082491) + +Li, A.-S., Bogaerts, L., & Theeuwes, J. (2022). Statistical learning of across-trial regularities during serial search. *Journal of Experimental Psychology: Human Perception and Performance*. [DOI](http://dx.doi.org/10.1037/xhp0000987) + +Verkhodanova, V., Coler, M., Jonkers, R., Timmermans, S., Maurits, N., de Jong, B., Lowie, W. (2022) A cross-linguistic perspective to classification of healthiness of speech in Parkinson's disease. *Journal of Neurolinguistics* [DOI](https://doi.org/10.1016/j.jneuroling.2022.101068) + +Rouy, M., de Gardelle, V., Reyes, G., Sackur, J., Vergnaud, J. C., Filevich, E., & Faivre, N. (2022). Metacognitive improvement: Disentangling adaptive training from experimental confounds. *Journal of Experimental Psychology: General*. [DOI](https://doi.org/10.1037/xge0001185) + +Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. *Atten Percept Psychophys* [DOI](https://doi.org/10.3758/s13414-021-02404-z) + +Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. *Journal of Vision*. [DOI](https://doi.org/10.1167/jov.22.2.11) + + +Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. *Journal of Personality*. [DOI](https://doi.org/10.1111/jopy.12705) + +Bogaerts, L., van Moorselaar, D., & Theeuwes, J. (2022). Does it help to expect distraction? Attentional capture is attenuated by high distractor frequency but not by trial-to-trial predictability. *Journal of Experimental Psychology: Human Perception and Performance*. [DOI](https://doi.org/10.1037/xhp0000986) + +Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. *Cognition* [DOI](https://doi.org/10.1016/j.cognition.2022.105052) + +Béna, J. & Corneille, O. (2022). Revisiting Dissociation Hypotheses with a Structural fit Approach: The Case of the Prepared Reflex Framework. *Journal of Experimental Social Psychology*. [DOI](10.1016/j.jesp.2022.104297) + +Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. *Mem Cogn*. [DOI](https://doi.org/10.3758/s13421-021-01256-0) + +Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. *Second Language Research*. [DOI](doi:10.1177/02676583211069735) + +Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. *Cognition* [DOI](10.1016/j.cognition.2021.104945). + + + +### 2021 +Shyr, MC, and Joshi, SS. (2021) Validation of the Bayesian sensory uncertainty model of motor adaptation with a remote experimental paradigm *IEEE 2nd International Conference on Human-Machine Systems (ICHMS)* [DOI](https://doi.org/10.1109/ICHMS53169.2021.9582639) + +Román-Caballero, R., Marotta, A., & Lupiáñez, J. (2021). Target–background segregation in a spatial interference paradigm reveals shared and specific attentional mechanisms triggered by gaze and arrows. Journal of Experimental Psychology: Human Perception and Performance, 47(11), 1561–1573. [DOI](https://doi.org/10.1037/xhp0000953) + +van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. [DOI](https://doi.org/10.1167/jov.21.12.3) + +Verkhodanova, V., Coler, M., Jonkers, R., & Lowie, W. (2021) How expertise and language familiarity influence perception of speech of people with Parkinson’s disease, *Clinical Linguistics & Phonetics*, [DOI](DOI: 10.1080/02699206.2021.2003433) + +Gorin, S. (2021). EXPRESS: Temporal grouping effects in verbal and musical short-term memory: Is serial order representation domain-general? *Quarterly Journal of Experimental Psychology*. [DOI](https://doi.org/10.1177/17470218211057466) + +van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. *Atten Percept Psychophys.* [DOI](https://doi.org/10.3758/s13414-021-02330-0) + +Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, *Cognition and Emotion* [DOI](10.1080/02699931.2021.1967884) + +Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, *Neuroscience of Consciousness*, Volume 2021, Issue 1, 2021, niab005, [DOI](https://doi.org/10.1093/nc/niab005) + +Tejada, J., Freitag, R.M.K., Pinheiro, B.F.M. et al (2021). Building and validation of a set of facial expression images to detect emotions: a transcultural study. *Psychological Research* . [DOI](https://doi.org/10.1007/s00426-021-01605-3) + +Singer-Landau, E., & Meiran, N. (2021). Cognitive appraisal contributes to feeling generation through emotional evidence accumulation rate: Evidence from instructed fictional reappraisal. *Emotion*. Advance online publication. [DOI](https://doi.org/10.1037/emo0001006) + +de Waard, J., Bogaerts, L., Van Moorselaar, D., Theeuwes, J. (2021). Surprisingly inflexible: statistically learned suppression of distractors generalizes across contexts Attention, Perception, and Psychophysics (in press). *Attention Perception & Psychophysics*. + +Jost, L., & Jansen, P. (2021). Are implicit affective evaluations related to mental rotation performance? *Consciousness and Cognition*, 94, 103178. [DOI](https://doi.org/10.1016/j.concog.2021.103178) + +Stark, C., Clemenson, G., Aluru, U., Hatamian, N., Stark, S. (2021). Playing Minecraft Improves Hippocampal-Associated Memory for Details in Middle Aged Adults. *Frontiers in Sports and Active Living*. 3. 685286. [DOI](https://doi.org/10.3389/fspor.2021.685286). + +Crivelli, D., Peviani, V., Salvato, G., Bottini, G. (2021). Exploring the Interaction Between Handedness and Body Parts Ownership by Means of the Implicit Association Test. *Frontiers in Human Neuroscience* 15. 681904. [DOI](https://doi.org/10.3389/fnhum.2021.681904). + +Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. *Neuroscience of Consciousness*. [DOI](https://doi.org/10.1093/nc/niab005). + +Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. *Sustainability*. 13. 7040. [DOI](https://doi.org/10.3390/su13137040). + +Ben-Yakov, A., Smith, V., Henson, R. (2021). The limited reach of surprise: Evidence against effects of surprise on memory for preceding elements of an event. *Psychonomic Bulletin & Review*. [DOI](https://doi.org/10.3758/s13423-021-01954-5). + +Dijkstra, N., Mazor, M., Kok, P., Fleming, S. (2021). Mistaking imagination for reality: Congruent mental imagery leads to more liberal perceptual detection. *Cognition*. 212. 104719. [DOI](https://doi.org/10.1016/j.cognition.2021.104719). + +Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. *Cognitive Science*. 45. [DOI](https://doi.org/10.1111/cogs.12959). + +Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. *The Japanese journal of psychology*. [DOI](https://doi.org/10.4992/jjpsy.92.20213). + +Krüger, A., Tünnermann, J., Stratmann, L., Dressler, F., Scharlau, I. (2021). TVA in the wild: Applying the theory of visual attention to game-like and less controlled experiments. *Open Psychology*. 3. 1-46. [DOI](https://doi.org/10.1515/psych-2021-0001) + +Steinke, A., Kopp, B. Lange, F. (2021). The Wisconsin Card Sorting Test: Split-Half Reliability Estimates for a Self-Administered Computerized Variant. *Brain Sciences*. 11. 529. [DOI](https://doi.org/10.3390/brainsci11050529) + +Zhang, C., Bernolet, S., Hartsuiker, RJ. (2021) Are there segmental and tonal effects on syntactic encoding? Evidence from structural priming in Mandarin. *Journal of Memory and Language* 119 [DOI](https://doi.org/10.1016/j.jml.2021.104220) + +Los, S.A., Nieuwenstein, J., Bouharab, A., Stephens, D.J., Meeter, M., Kruijne, W. (2021) The warning stimulus as retrieval cue: The role of associative memory in temporal preparation. *Cognitive Psychology* 125(2):101378 [DOI](https://doi.org/10.1016/j.cogpsych.2021.101378) + +Vogt, A., Hauber, R., Kuhlen, A.K. et al. (2021) Internet-based language production research with overt articulation: Proof of concept, challenges, and practical advice. *Behav Res* (2021). [DOI](https://doi.org/10.3758/s13428-021-01686-3) + +Neto, P. A. S. O., Cui, A.-X., Rojas, P., Vanzella, P., & Cuddy, L. L. (2021). Not just cents: Physical and psychological influences on interval perception. *Psychomusicology: Music, Mind, and Brain.* Advance online publication. [DOI](https://doi.org/10.1037/pmu0000272) + +Los, S.A., Nieuwenstein, J., Bouharab, A., Stephens, D.J., Meeter, M., Kruijne, W. (2021) The warning stimulus as retrieval cue: The role of associative memory in temporal preparation. *Cognitive Psychology*, 125, 101378. [DOI](10.1016/j.cogpsych.2021.101378) + +Ren, K., & Gunderson, E. A. (2021). The dynamic nature of children’s strategy use after receiving accuracy feedback in decimal comparisons. *Journal of Experimental Child Psychology*, 202, 105015. [DOI](https://doi.org/10.1016/j.jecp.2020.105015) + + +### 2020 + +Krüger, A., Tünnermann, J. Stratmann, L., Briese, L., Dressler, F. and Scharlau, I. (2020) TVA in the wild: Applying the theory of visual attention to game-like and less controlled experiments, *Open Psychology*, 2020. + +Vari, J. & Tamburelli, M. (2020) Standardisation: bolstering positive attitudes towards endangered language varieties? Evidence from implicit attitudes. *Journal of Multilingual and Multicultural Development*. [DOI](https://doi.org/10.1080/01434632.2020.1829632) + +Verkhodanova V., Trčková D., Coler M., Lowie W. (2020) More than Words: Cross-Linguistic Exploration of Parkinson’s Disease Identification from Speech. In: Karpov A., Potapova R. (eds) Speech and Computer. SPECOM 2020. Lecture Notes in Computer Science, vol 12335. Springer, Cham. [DOI](https://doi.org/10.1007/978-3-030-60276-5_59) + +Scarpina, F. (2020) Detection and Recognition of Fearful Facial Expressions During the Coronavirus Disease (COVID-19) Pandemic in an Italian Sample: An Online Experiment. *Front. Psychol.* [DOI](https://doi.org/10.3389/fpsyg.2020.02252) + +Qiu, M., Johns, B.T. (2020) Semantic diversity in paired-associate learning: Further evidence for the information accumulation perspective of cognitive aging. *Psychonomic Bulletin & Review* 27, 114–121. [DOI](https://link.springer.com/article/10.3758%2Fs13423-019-01691-w) + +Dolscheid, S., Çelik, S., Erkan, H., Küntay, A., & Majid, A. (2020). Space-pitch associations differ in their susceptibility to language. *Cognition*, 196, 104073. [DOI](https://doi.org/10.1016/j.cognition.2019.104073) + +Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. *Pers Ubiquit Comput* (2020). [DOI](https://doi.org/10.1007/s00779-020-01388-1) + +### 2019 + +Richan, E., & Rouat, J. (2019). A study comparing shape, colour and texture as visual labels in audio sample browsers. Proceedings of the 14th International Audio Mostly Conference: A Journey in Sound, 223–226. [DOI](https://doi.org/10.1145/3356590.3356624) + +Cooper, E., Greve, A., & Henson, R. N. (2019). Investigating Fast Mapping Task Components: No Evidence for the Role of Semantic Referent nor Semantic Inference in Healthy Adults. *Frontiers in psychology*, 10, 394. [DOI](https://doi.org/10.3389/fpsyg.2019.00394) + +MacGregor, L. J., Rodd, J. M., Gilbert, R. A., Hauk, O., Sohoglu, E., & Davis, M. H. (2019). The Neural Time Course of Semantic Ambiguity Resolution in Speech Comprehension. *Journal of Cognitive Neuroscience*, 1–23. [DOI](https://doi.org/10.1162/jocn_a_01493) + +Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. *Developmental Psychology*, 55(11), 2263–2274. [DOI](10.1037/dev0000797) + +### 2018 + +Kolling, N., Scholl, J., Chekroud, A., Trier, H. A., & Rushworth, M. F. S. (2018). Prospection, Perseverance, and Insight in Sequential Behavior. *Neuron*, 99(5), 1069-1082.e7. [DOI](https://doi.org/10.1016/j.neuron.2018.08.018) + +Presaghi, F., & Rullo, M. (2018). Is Social Categorization Spatially Organized in a “Mental Line”? Empirical Evidences for Spatial Bias in Intergroup Differentiation. *Frontiers in Psychology*, 9. [DOI](https://doi.org/10.3389/fpsyg.2018.00152) + +### 2017 + +Niemann, M., Elischberger, F., Diedam, P., Hopkins, J., Thapa, R., de Siqueira Braga, D., … de L. Neto, F. B. (2017). A Novel Serious Game for Trust-Related Data Collection in Supply Chains. In M. Alcañiz, S. Göbel, M. Ma, M. Fradinho Oliveira, J. Baalsrud Hauge, & T. Marsh (Eds.), *Serious Games* (pp. 121–125). [DOI](https://doi.org/10.1007/978-3-319-70111-0_11) + +Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. *Psychological Research*, 1–18. [DOI](https://doi.org/10.1007/s00426-017-0962-7) diff --git a/versioned_docs/version-3.9.1/Overview/Run-an-experiment-with-JATOS-Workflow.md b/versioned_docs/version-3.9.1/Overview/Run-an-experiment-with-JATOS-Workflow.md new file mode 100644 index 0000000000..e3b3fe1fe3 --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/Run-an-experiment-with-JATOS-Workflow.md @@ -0,0 +1,44 @@ +--- +title: Run an experiment with JATOS - Workflow +slug: /Run-an-experiment-with-JATOS-Workflow.html +sidebar_position: 6 +--- + +## Workflow: What JATOS does + +When you start working with studies online, it can be hard to see what exactly JATOS does. This page, explaining the general workflow, might help to clarify things. Follow the links on each section for more details. + +![general workflow](/img/generalWorkflow.png) + +## Step 1: Create/edit HTML, JS, and CSS files (Prepare your study) + +We recommend that you always start to work on a new study in a *local* installation of JATOS. That means, [download and run JATOS on your local computer](Installation.html#easy-installation-on-your-local-computer). +The main advantage of this is that you have easy access to all your HTML files and assets and can move them around, delete, and replace without any fuss. + +Learn more about [creating and editing HTML/JS code](Create-a-new-study.html) + +## Step 2: Deploy files to a server (Make your study available in the Internet) + +Once your study scripts are complete and bug-free, you need to make them available through the Internet. For that you will need, of course, [a server](Bring-your-JATOS-online.html). + +If you have a server already, you will need to take your ready-to-run study from your local installation and deploy it to the server. In order to do this: +1. On your *local* JATOS installation, where your study is, click on the study you want to export on the left sidebar. +1. On the Study bar, click Export. A pop-up window will appear. Save the [_.jzip_](JATOS-Study-Archive-JZIP.html) file wherever you like on your computer. +1. On your *server* installation, simply click Import. + +Done. + +There are a few important details in [deploying your study to a server](Deploy-to-a-server-installation.html) + +Also have a look at [Bring your JATOS online](Bring-your-JATOS-online.html). + +## Step 3: Collect data +Read about [Study Links](Run-your-Study-with-Study-Links.html) to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of [worker types](Worker-Types.html) you need. You can (but don't have to) use [MTurk](Connect-to-Mechanical-Turk.html) or [Prolific](Use-Prolific.html) to get participants. + +## Step 4: Download and analyze data +One of JATOS' features is that you can manage the results stored in the database without having to type SQL commands in a terminal. Instead, just do this [using the GUI](Manage-Results.html). + +You'll download a .csv or JSON-formatted text file (depending on how you wrote your JavaScript). We always recommend JSON format because it's more flexible and robust, and use [JSONlab](https://de.mathworks.com/matlabcentral/fileexchange/33381-jsonlab-a-toolbox-to-encode-decode-json-files) to read the data into Matlab and the [rjson](https://cran.r-project.org/web/packages/rjson/index.html) package for R. + +With this, you can import your JSON data into Matlab or R; or a .csv into Excel, JAGS or SPSS. From here on, you know the drill. + diff --git a/versioned_docs/version-3.9.1/Overview/Whats-JATOS.md b/versioned_docs/version-3.9.1/Overview/Whats-JATOS.md new file mode 100644 index 0000000000..ed1393c0de --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/Whats-JATOS.md @@ -0,0 +1,35 @@ +--- +title: What is JATOS +slug: /Whats-JATOS.html +sidebar_position: 1 +hide_table_of_contents: true +--- + +JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server. + +**New: [MindProbe](https://mindprobe.eu/), a free server for hosting online experiments. Powered by JATOS. Sponsored by the [European Society for Cognitive Psychology (ESCoP)](https://www.escop.eu/) with [Journal of Cognition](https://www.journalofcognition.org/) as their official journal and [OpenSesame](https://osdoc.cogsci.nl/).** + +**Please complete our short [survey](https://forms.gle/Jtjw4LxpyWVFEtG17) on how (much) you use JATOS (ca. 3 min). It’s very important for us!** + +### JATOS at a glance +* Run studies on your **own server**. This means that you keep complete control over who can access your result data and can comply with your ethics. +* Studies run on **mobile phones, tablets, desktops, and lab computers** - any device with a browser. +* Use tools like **jsPsych**, **lab.js**, **OSWeb/OpenSesame**, or **PsyToolkit** to prepare your study - or write all **HTML / JavaScript / CSS** yourself and have full control. +* **Run group studies** where multiple workers interact with each other in real-time. +* It’s GUI-based, so there's no need to use the terminal to talk to your server. +* Recruit participants via **MTurk**, **Prolific** etc. +* It's **open-source and free** to use. +* **Manage participants**, to e.g. make sure that each participant does your study only **once**. +* **Export/Import** studies to facilitate exchange with other researchers. +* Use the **JATOS API** to integrate with your tools +* You can **try out** [JATOS on _cortex_, our test server](JATOS-Tryout-Server.html). + + +Watch an introduction video: + + +

+ +JATOS is free and open-source and released under the [Apache 2 Licence](http://www.apache.org/licenses/LICENSE-2.0.html). The source code is available on [GitHub](https://github.com/JATOS/JATOS). + +[Over 200 studies](Papers-Citing-JATOS.html) have sucessfully collected data using JATOS already! Please [cite us](http://journals.plos.org/plosone/article?id=10.1371/journal.pone.0130834) if you use JATOS for your research. diff --git a/versioned_docs/version-3.9.1/Overview/_category_.json b/versioned_docs/version-3.9.1/Overview/_category_.json new file mode 100644 index 0000000000..e224ed81cd --- /dev/null +++ b/versioned_docs/version-3.9.1/Overview/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Overview", + "position": 1 +} diff --git a/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-API.md b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-API.md new file mode 100644 index 0000000000..2d273e4b83 --- /dev/null +++ b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-API.md @@ -0,0 +1,260 @@ +--- +title: JATOS API +slug: /JATOS-API.html +sidebar_position: 3 +--- + +:::info +Using the JATOS API requires some **advanced knowledge** of HTTP and how to call APIs from e.g. a programming language or a terminal. If you just want to run a study with JATOS this is probably not what you need. Anything that you can do (programmatially) with the API can also be done (by hand) with JATOS' GUI. +::: + +## Introduction + +Since version 3.8.1 JATOS offers an (HTTP) API to make integrating JATOS into other tools easier. One common usage of the API is to call JATOS directly from Python, R, Matlab (or any other programming language) in an automated and programatic fashion. + +Things that are possible with the API: + +* **Import/export studies** +* Update your study by uploading/downloading/deleting single **study assets files** +* **Export results** +* Export **study/componnent properties** +* Get **study codes** (to build study links that can be distributed to participants) + + +## Have a look and try it out +You can even try out the API with your local JATOS. Here's how: +1. [Generate a token](JATOS-API.html#how-to-generate-a-token) in your local JATOS. (The JATOS API uses _personal access tokens_ with _bearer authentication_.) +1. Copy your token +1. Go to [petstore.swagger.io](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/JATOS/JATOS/main/jatos-api.yaml). You'll see all API endpoints and their descriptions. +1. At the top of the Swagger page, you'll find a green 'Authorize' button. Paste the JATOS token into _Authorize_ -> _Bearer Auth_. Don't forget to click on _Authorize_. +1. Choose the server `http://localhost:9000` (probably already set) +1. Try it out! (Click on each link to try the corresponding endpoint with pre-loaded defaults) + +## OpenAPI specification + +The JATOS API uses [OpenAPI 3 for specification](https://github.com/JATOS/JATOS/blob/main/jatos-api.yaml). You can use [petstore.swagger.io](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/JATOS/JATOS/main/jatos-api.yaml) to have an easy navigatable page. + +The API is work in progress (this is the first version). To request any additional endpoints, please write a [GitHub issue](https://github.com/JATOS/JATOS/issues). + + +## Authentication + +The JATOS API uses **bearer authentication**. It's pretty simple. + +From [swagger.io](https://swagger.io/docs/specification/authentication/bearer-authentication/): + +> Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name "Bearer authentication" can be understood as "give access to the bearer of this token." The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources. + +Every HTTP request to the API needs this header (replace `` with your token): + +``` +Authorization: Bearer +``` + +And an example in different tools/languages with the endpoint `/jatos/api/v1/admin/token` that just returns some info about the used token: + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + +```shell +curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token +``` + + + + +```py +import requests + +headers = { + 'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f', +} +response = requests.post('https://example.com/jatos/api/v1/admin/token', headers=headers) +``` + + + + +```r +require(httr) + +headers = c( + `Authorization` = "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" +) +res <- httr::GET(url = "https://example.com/jatos/api/v1/admin/token", httr::add_headers(.headers=headers)) +``` + + + + +```js +fetch('https://example.com/jatos/api/v1/admin/token', { + headers: { + 'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f' + } +}); +``` + + + + +```matlab +%% HTTP Interface +import matlab.net.* +import matlab.net.http.* + +header = HeaderField('Authorization', 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f'); +uri = URI('https://example.com/jatos/api/v1/admin/token'); +response = RequestMessage('get', header).send(uri.EncodedURI); +``` + + + + +```powershell +$headers=@{} +$headers.Add("Authorization", "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f") +$response = Invoke-WebRequest -Uri 'https://www.example.com/jatos/api/v1/admin/token' -Method GET -Headers $headers +``` + + + + + +## Personal access tokens + +The JATOS API uses personal access tokens (PATs or API tokens). + +From [wikipedia](https://en.wikipedia.org/wiki/Personal_access_token): + +> a personal access token (or PAT) is a string of characters that can be used to authenticate a user when accessing a computer system instead of the usual password. Though associated with a single account, multiple PATs may be created, and can be manipulated independently of the password associated with that account, including creation and revocation of PATs without altering the password. + +Unlike other systems (e.g. GitHub) JATOS' tokens have no roles or scopes. A token has the same access as the user they are associated with. Therefore, naturally, a token can only be used to access studies or their result data if the associated user is a member of this study. Only _admin tokens_ (tokens associated with an admin user) can access the administration endpoints. + +### How to generate a token + +Go to the user menu (click on your name in the top-right header). Then click the button _My API tokens_. + +![API token 1](/img/v39x/api_tokens_1.png) + +In the pop-up window click the button _New Token". Then choose a descriptive _name_ (doesn't have to be unique). Choose the time period when the token is about to expire. Click _Generate_. + +![API token 1](/img/v39x/api_tokens_2.png) + +Now your token will be shown. **Copy it to a safe place**. **It will never be shown to you again**. + +![API token 1](/img/v39x/api_tokens_3.png) + +In the token overview windows you can temporarily deactivate a token or delete it altogether. + +![API token 1](/img/v39x/api_tokens_4.png) + + +## How to import a study + +The endpoint to import a study, `/jatos/api/v1/study`, can be a bit tricky. It uses POST request with the header `Content-Type: multipart/form-data` to upload the a study archive file (JZIP) in binary format. + +Here are some examples in different tools/languages. They all upload a JZIP file named `test.jzip`: + + + + +```shell +curl -X 'POST' 'https://example.com/jatos/api/v1/study' -H 'accept: application/json' -H 'Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f' -H 'Content-Type: multipart/form-data' -F 'study=@test.jzip' +``` + + + + +```py +import requests + +headers = { + 'accept': 'application/json', + 'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f', + # requests won't add a boundary if this header is set when you pass files= + # 'Content-Type': 'multipart/form-data', +} + +files = { + 'study': open('test.jzip', 'rb'), +} + +response = requests.post('https://example.com/jatos/api/v1/study', headers=headers, files=files) +``` + + + + +```r +require(httr) + +headers = c( + `Authorization` = "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" +) +res <- httr::GET(url = "https://example.com/jatos/api/v1/admin/token", httr::add_headers(.headers=headers)) +``` + + + + +```js +const form = new FormData(); +form.append('study', File([''], 'test.jzip')); + +fetch('https://example.com/jatos/api/v1/study', { + method: 'POST', + headers: { + 'accept': 'application/json', + 'Authorization': 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f', + 'Content-Type': 'multipart/form-data' + }, + body: form +}); +``` + + + + +```matlab +%% HTTP Interface +import matlab.net.* +import matlab.net.http.* +import matlab.net.http.io.* + +header = [ + field.AcceptField(MediaType('application/json')) + HeaderField('Authorization', 'Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f') + HeaderField('Content-Type', 'multipart/form-data') +]'; +uri = URI('https://example.com/jatos/api/v1/study'); +body = MultipartFormProvider('study', FileProvider('test.jzip')); +response = RequestMessage('post', header, body).send(uri.EncodedURI); +``` + + + + +```powershell +$headers=@{} +$headers.Add("accept", "application/json") +$headers.Add("Authorization", "Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f") +$headers.Add("Content-Type", "multipart/form-data") +$response = Invoke-WebRequest -Uri 'https://example.com/jatos/api/v1/study' -Method POST -Headers $headers + +``` + + + + + +## Deactivate the JATOS API + +By default the API is activated and ready to use. If, for whatever reasons, you want to turn it off, edit the `conf/jatos.conf` (or `conf/production.conf` in version < 3.8.3) in the JATOS installation folder. Search for `jatos.api.allowed` and remove the `#`: + +``` +jatos.api.allowed = false +``` diff --git a/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Results-Archive-JRZIP.md b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Results-Archive-JRZIP.md new file mode 100644 index 0000000000..be97830933 --- /dev/null +++ b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Results-Archive-JRZIP.md @@ -0,0 +1,282 @@ +--- +title: JATOS Results Archive (JRZIP) +slug: /JATOS-Results-Archive-JRZIP.html +sidebar_position: 5 +--- + +:::info +This is **advanced knowledge** about JATOS. If you just want to use JATOS to run a study it is not necessary to read this. +::: + +## Introduction + +A JRZIP ("JATOS study results archive") is a file package format used to export results from JATOS instances. A JRZIP aggregates the results data, result files and associated metadata into one file for distribution. They are built on the ZIP format and have a _.jrzip_ file extension. Hence every ZIP unpacker can be used to get to the files. + + +## JRZIP File system structure + +A JRZIP file is organized by study results. Each study result folder (named _study_result_x_, _x_ being the study result ID) contains the folders for the component results (named _comp_result_y_, _y_ being the component result ID) that belong to the components of the study. Each component result folder contains the uploaded result files in the _files_ folder and the result data in the _data.txt_ file. + +``` +/ +├── study_result_1 +│ ├── comp_result_1 +│ │ ├── files +│ │ └── data.txt +│ ├── comp_result_2 +│ ├── comp_result_2 +│ └── ... +├── study_result_2 +├── study_result_3 +│ ... +└── metadata.json +``` + + +## Metadata JSON Schema + +```json +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "$id": "http://example.com/example.json", + "type": "object", + "title": "Root", + "required": [ + "data" + ], + "properties": { + "apiVersion": { + "type": "string", + "title": "The API version", + "examples": [ + "1.0.0" + ] + }, + "data": { + "type": "array", + "title": "All data", + "items": { + "type": "object", + "title": "Study IDs, title and results", + "required": [ + "studyId", + "studyUuid", + "studyTitle", + "studyResults" + ], + "properties": { + "studyId": { + "type": "integer", + "title": "Study ID" + }, + "studyUuid": { + "type": "string", + "title": "Study UUID" + }, + "studyTitle": { + "type": "string", + "title": "Study's title" + }, + "studyResults": { + "type": "array", + "title": "List of study results", + "items": { + "type": "object", + "title": "Study result", + "description": "A study result contains one or multiple component results", + "required": [ + "id", + "uuid", + "studyCode", + "startDate", + "endDate", + "duration", + "lastSeenDate", + "studyState", + "message", + "workerId", + "workerType", + "batchId", + "batchUuid", + "batchTitle", + "groupId", + "componentResults" + ], + "properties": { + "id": { + "type": "integer", + "title": "Study result ID" + }, + "uuid": { + "type": "string", + "title": "Study result UUID" + }, + "studyCode": { + "type": "string", + "title": "Study code" + }, + "comment": { + "type": "string", + "title": "Comment from study link (only PersonalSingle and PersonalMultiple)" + }, + "startDate": { + "type": "integer", + "title": "Epoch time of the start date" + }, + "endDate": { + "type": "integer", + "title": "Epoch time of the end date" + }, + "duration": { + "type": "string", + "title": "Study run duration in hh:mm:ss" + }, + "lastSeenDate": { + "type": "integer", + "title": "Epoch time of the last seen date" + }, + "studyState": { + "type": "string", + "title": "Study result state", + "description": "One of: PRE (Preview of study - exists only in PersonalSingle GeneralSingle worker), STARTED (Study was started), DATA_RETRIEVED (Study's jsonData were retrieved), FINISHED (Study successfully finished), ABORTED (Study aborted by worker), FAIL (Something went wrong)" + }, + "message": { + "type": "string", + "title": "Message from the study run" + }, + "workerId": { + "type": "integer", + "title": "Worker ID" + }, + "workerType": { + "type": "string", + "title": "Worker type", + "description": "On of: GeneralMultiple, GeneralSingle, Jatos, MTSandbox, MT, PersonalMultiple, PersonalSingle" + }, + "batchId": { + "type": "integer", + "title": "Batch ID" + }, + "batchUuid": { + "type": "string", + "title": "Batch UUID" + }, + "batchTitle": { + "type": "string", + "title": "Batch title" + }, + "groupId": { + "type": "string", + "title": "Group ID" + }, + "componentResults": { + "type": "array", + "title": "List of component results", + "items": { + "type": "object", + "title": "component result", + "required": [ + "id", + "componentId", + "componentUuid", + "startDate", + "endDate", + "duration", + "componentState", + "path", + "data", + "files" + ], + "properties": { + "id": { + "type": "integer", + "title": "Component result ID" + }, + "componentId": { + "type": "integer", + "title": "Component ID" + }, + "componentUuid": { + "type": "string", + "title": "Component UUID" + }, + "startDate": { + "type": "integer", + "title": "Epoch time of the start date" + }, + "endDate": { + "type": "integer", + "title": "Epoch time of the end date" + }, + "duration": { + "type": "string", + "title": "Component run duration in hh:mm:ss" + }, + "componentState": { + "type": "string", + "title": "Component result state", + "description": "One of: STARTED, DATA_RETRIEVED, FINISHED, RELOADED, ABORTED, FAIL (deprecated: RESULTDATA_POSTED)" + }, + "path": { + "type": "string", + "title": "Path", + "description": "Path to the component result folder in the archive" + }, + "data": { + "type": "object", + "title": "Data properties", + "description": "The actual result data are in an extra file called 'data.txt'", + "required": [ + "size", + "sizeHumanReadable" + ], + "properties": { + "size": { + "type": "integer", + "title": "Data size in byte" + }, + "sizeHumanReadable": { + "type": "string", + "title": "Human readable data size" + } + } + }, + "files": { + "type": "array", + "title": "List of file properties", + "items": { + "type": "object", + "title": "Properties of one file", + "required": [ + "filename", + "size", + "sizeHumanReadable" + ], + "properties": { + "filename": { + "type": "string", + "title": "Filename" + }, + "size": { + "type": "integer", + "title": "File size in byte" + }, + "sizeHumanReadable": { + "type": "string", + "title": "Human readable file size" + } + } + } + } + } + } + } + } + } + } + } + } + } + } +} +``` diff --git a/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Study-Archive-JZIP.md b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Study-Archive-JZIP.md new file mode 100644 index 0000000000..96407587f5 --- /dev/null +++ b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS-Study-Archive-JZIP.md @@ -0,0 +1,277 @@ +--- +title: JATOS Study Archive (JZIP) +slug: /JATOS-Study-Archive-JZIP.html +sidebar_position: 4 +--- + +:::info +This is **advanced knowledge** about JATOS. If you just want to use JATOS to run a study it is not necessary to read this. +::: + + +## Introduction + +A JZIP ("JATOS study archive") is a file package format used to exchange JATOS studies between different JATOS instances. A JZIP aggregates the study assets and associated metadata (study properties) into one file for distribution. They are built on the ZIP format and have a _.jzip_ file extension. + +### JZIP File system structure + +``` +/ +├── study assets directory (actual name is defined in the study properties) +│ ├── some asset file +│ ├── some asset file +│ └── ... +└── JAS file (containing the study properties in JSON format with a .jas file extension) +``` + +### Study assets directory + +This is a copy of the study assets directory. + +### JAS file schema + +The JAS file contains the study properties in JSON format. + +#### Example of a JAS file + + +```json +{ + "version": "3", + "data": { + "uuid": "537cfff1-de92-1d80-264c-6b589e82f6de", + "title": "Simple Reaction Time Task", + "description": "Here we descibe the study.", + "groupStudy": false, + "linearStudy": false, + "allowPreview": false, + "dirName": "simple_rt_task", + "comments": "", + "jsonData": "{\"a\":\"test\",\"b\":5}", + "endRedirectUrl": "", + "studyEntryMsg": null, + "componentList": [ + { + "uuid": "dea21111-a966-5b24-9f15-a89fefa3f711", + "title": "Introduction and Consent", + "htmlFilePath": "intro.html", + "reloadable": true, + "active": true, + "comments": "", + "jsonData": null + }, + { + "uuid": "970a92f0-b966-4b2f-bf15-b89fefa3f911", + "title": "Experiment", + "htmlFilePath": "experiment.html", + "reloadable": false, + "active": true, + "comments": "", + "jsonData": null + } + ], + "batchList": [ + { + "uuid": "9c7992ca-aa24-4081-8b0e-ee70f49cd65f", + "title": "Default", + "active": true, + "maxActiveMembers": null, + "maxTotalMembers": null, + "maxTotalWorkers": null, + "allowedWorkerTypes": [ + "PersonalSingle", + "Jatos", + "PersonalMultiple" + ], + "comments": null, + "jsonData": null + } + ] + } +} +``` + +#### JSON Schema of a JAS file + +```json +{ + "$schema": "https://json-schema.org/draft/2019-09/schema", + "$id": "http://example.com/example.json", + "type": "object", + "title": "Root Schema", + "required": [ + "version", + "data" + ], + "properties": { + "version": { + "type": "string", + "title": "Version of this study property schema" + }, + "data": { + "type": "object", + "title": "Study properties", + "required": [ + "uuid", + "title", + "dirName", + "componentList" + ], + "properties": { + "uuid": { + "type": "string", + "title": "Study UUID" + }, + "title": { + "type": "string", + "title": "Title" + }, + "description": { + "type": "string", + "title": "Description" + }, + "groupStudy": { + "type": "boolean", + "default": false, + "title": "Group study flag" + }, + "linearStudy": { + "type": "boolean", + "default": false, + "title": "Linear study flag" + }, + "allowPreview": { + "type": "boolean", + "default": false, + "title": "Allow preview flag" + }, + "dirName": { + "type": "string", + "title": "Study assets directory name" + }, + "comments": { + "type": "string", + "title": "Comments" + }, + "jsonData": { + "type": "string", + "title": "JSON data" + }, + "endRedirectUrl": { + "type": "string", + "title": "End redirect URL" + }, + "studyEntryMsg": { + "type": "string", + "title": "Study entry message" + }, + "componentList": { + "type": "array", + "title": "List of components", + "items": { + "type": "object", + "title": "Component", + "required": [ + "uuid", + "title", + "htmlFilePath" + ], + "properties": { + "uuid": { + "type": "string", + "title": "Component UUID" + }, + "title": { + "type": "string", + "title": "Title" + }, + "htmlFilePath": { + "type": "string", + "title": "HTML file path" + }, + "reloadable": { + "type": "boolean", + "default": false, + "title": "Reloadable component flag" + }, + "active": { + "type": "boolean", + "default": true, + "title": "Component active flag" + }, + "comments": { + "type": "string", + "title": "Comments" + }, + "jsonData": { + "type": "null", + "title": "JSON data" + } + } + } + }, + "batchList": { + "type": "array", + "title": "List of batches", + "items": { + "type": "object", + "title": "Batch", + "required": [ + "uuid", + "title", + "allowedWorkerTypes" + ], + "properties": { + "uuid": { + "type": "string", + "title": "Batch UUID" + }, + "title": { + "type": "string", + "title": "Title" + }, + "active": { + "type": "boolean", + "default": true, + "title": "Batch active flag" + }, + "maxActiveMembers": { + "type": "integer", + "default": "null", + "title": "Max active members" + }, + "maxTotalMembers": { + "type": "integer", + "default": "null", + "title": "Max total members" + }, + "maxTotalWorkers": { + "type": "integer", + "default": "null", + "title": "Max total workers" + }, + "allowedWorkerTypes": { + "type": "array", + "title": "Allowed worker types", + "description": "Possible items are: GeneralMultiple, GeneralSingle, Jatos, MTSandbox, MT, PersonalMultiple, PersonalSingle" + "items": { + "type": "string", + "title": "Worker type" + } + }, + "comments": { + "type": "string", + "title": "Comments" + }, + "jsonData": { + "type": "string", + "title": "JSON data" + } + } + } + } + } + } + } +} +``` diff --git a/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS_Configuration.md b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS_Configuration.md new file mode 100644 index 0000000000..a0d4f9f5d4 --- /dev/null +++ b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/JATOS_Configuration.md @@ -0,0 +1,1052 @@ +--- +title: JATOS Configuration +slug: /JATOS_Configuration.html +sidebar_position: 2 +--- + +JATOS' properties can be configured in three different ways: + +1. via a **config file** (named _jatos.conf_ or _production.conf_) +1. via **command-line** arguments +1. via **environment** variables (possible for only a few of the properties) + +The config file is located in the JATOS folder under _./conf_ and is named _jatos.conf_ for versions >= 3.8.3 and _production.conf_ for versions < 3.8.3. It uses the [HOCON format](https://github.com/lightbend/config/blob/main/HOCON.md). **Remember to always restart JATOS after making any changes to a config file.** + +Command-line argument names are usually the same as the names in the config file except that they are prefixed with `-D` (except JVM arguments that have a `-J`), e.g. `jatos.urlBasePath` and `-Djatos.urlBasePath`. + +Command-line arguments can be appended to JATOS' `loader.sh start` command. E.g., here is the command with the two arguments `-Djatos.urlBasePath` and `-Djatos.tmpPath`: + + ~~~shell + ./loader.sh start -Djatos.urlBasePath="/mybasepath/" -Djatos.tmpPath="/my/tmp/dir" + ~~~ + + +## JVM arguments + +JVM arguments (arguments for the Java Virtual Machine) are special since they are not directly intended for JATOS but for the JVM running JATOS. They can **only be specified via command line arguments** and have to be prefixed with `-J`. + +One commonly used JVM argument is `-Xmx`. It limits JATOS's memory usage (JVM's maximum heap memory usage to be precise). It has to be written as `-J-Xmx`, e.g. to allow 4GB memory `-J-Xmx4G`. + +## HTTP config + +### Address and port + +By default JATOS binds to all locally available IP addresses including 127.0.0.1 on port 9000. Usually JATOS is installed together with a reverse proxy (e.g Nginx or Apache) but if you don't want to use a proxy, you have to set up the hostname or IP address and the port in one of the ways. + +1. Via **config file** properties + + * **For v3.8.1 and lower)** `play.server.http.address` and `play.server.http.port` + * **For v3.8.2 and higher)** `jatos.http.address` and `jatos.http.port` + + Example: + + ~~~shell + jatos.http.address = 1.2.3.4 + jatos.http.port = 80 + ~~~ + +1. Via **command-line** arguments + + * **For v3.8.1 and lower)** `-Dplay.server.http.address` and `-Dplay.server.http.port` + * **For v3.8.2 and higher)** `-Djatos.http.address` and `-Djatos.http.port` + + Example: + + ~~~shell + -Djatos.http.address=1.2.3.4 -Djatos.http.port=80 + ~~~ + + +### Server idle timeout + +The idle timeout for an open connection after which it will be closed. Set to `null` or `infinite` to disable the timeout, but notice that this is not encouraged since timeouts are important mechanisms to protect your servers from malicious attacks or programming mistakes. Default is 75 seconds. + +1. Via **config file** property `play.server.http.idleTimeout` + + Example: + + ~~~shell + play.server.http.idleTimeout = 100s + ~~~ + +1. Via **command-line** argument `-Dplay.server.http.idleTimeout` + + Example: + + ~~~shell + -Dplay.server.http.idleTimeout=100s + ~~~ + + +### Request timeout + +How long can a request take until it times out. Set to `null` or `infinite` to disable the timeout. Default is `infinite`. + +1. Via **config file** property `play.server.akka.requestTimeout` + + Example: + + ~~~shell + play.server.akka.requestTimeout = 100s + ~~~ + +1. Via **command-line** argument `-Dplay.server.akka.requestTimeout` + + Example: + + ~~~shell + -Dplay.server.akka.requestTimeout=100s + ~~~ + + +### URL base path + +JATOS can be configured to use an base path. E.g we have the host _www\.example\.org_ and let JATOS run under _mybasepath_ so that all URLs start with _www\.example\.org/mybasepath/_. + +**The path always has to start and end with a "/".** And keep in mind that if you add a base path to JATOS' URL you have to adjust all absolute paths to the study assets (in HTML and JavaScript files) too - [or use relative paths](Adapt-pre-written-code-to-run-it-in-JATOS.html#create-the-study-in-jatos) (which is recommended anyway). + +1. Via **config file** properties + + * **For v3.8.1 and lower)** `play.http.context` + * **For v3.8.2 and higher)** `jatos.urlBasePath` + + Example: + + ~~~shell + jatos.urlBasePath = "/mybasepath/" + ~~~ + +1. Via **command-line** arguments + + * **For v3.8.1 and lower)** `-Dplay.http.context` + * **For v3.8.2 and higher)** `-Djatos.urlBasePath` + + ~~~shell + -Djatos.urlBasePath="/mybasepath/" + ~~~ + +1. Via **environment** variable `JATOS_URL_BASE_PATH` + + ~~~shell + JATOS_URL_BASE_PATH="/mybasepath/" + ~~~ + + +### X-Frame-Options header + +The [X-Frame-Options header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Frame-Options) can be used to allow or disallow embedding a JATOS study in an [iframe](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) (or similar embedding techniques). Possible values are `DENY` (completely disallow iframes), `SAMEORIGIN` (embedding page has the same origin as the iframe), or `null` (allow iframes everywhere). By default it set to `SAMEORIGIN`. + +1. Via **config file** property `play.filters.headers.frameOptions` + + Example: + + ~~~shell + play.filters.headers.frameOptions = null + ~~~ + +1. Via **command-line** argument `-Dplay.filters.headers.frameOptions` + + Example: + + ~~~shell + -Dplay.filters.headers.frameOptions=null + ~~~ + + +## Trusted certificates + +It's possible to add multiple certificates, e.g. for for encrypted LDAP. _type_ can be `PKCS12`, `JKS` or `PEM`. + +1. Only via **config file** property `play.ws.ssl.trustManager.stores` + + ~~~shell + play.ws.ssl.trustManager.stores = [ { type = "PEM", path = "conf/certs/ca.pem" } ] + ~~~ + + +## Study assets root path + +The study assets root folder is the location where all study's HTML, JavaScript files etc. are stored. By default it is located in the JATOS folder and has the default name _study_assets_root_, except when JATOS runs in a Docker container, where it is under _/opt/jatos_data/study_assets_root"_ + +1. Via **config file** property `jatos.studyAssetsRootPath` + + ~~~shell + jatos.studyAssetsRootPath = "/path/to/my/assets/root/folder" + ~~~ + +1. Via **command-line** argument `-Djatos.studyAssetsRootPath` + + ~~~shell + -Djatos.studyAssetsRootPath="/path/to/my/assets/root/folder" + ~~~ + +1. Via **environment** variable `JATOS_STUDY_ASSETS_ROOT_PATH` + + ~~~shell + JATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder" + ~~~ + + +## Temporary directory path + +(Only in version >= 3.8.3) + +JATOS uses a directory to temporarily store files, e.g. during study import. By default the system's temporary directory is used (on Linux/Unix _/tmp_ or on Windows _c:\temp_), except when JATOS runs in a Docker container, when it is under _/opt/jatos_data/tmp_. + +1. Via **config file** property `jatos.tmpPath` + + ~~~shell + jatos.tmpPath = "/my/tmp/dir" + ~~~ + +1. Via **command-line** argument `-Djatos.tmpPath` + + ~~~shell + -Djatos.tmpPath="/my/tmp/dir" + ~~~ + +1. Via **environment** variable `JATOS_TMP_PATH` + + ~~~shell + JATOS_TMP_PATH="/my/tmp/dir" + ~~~ + + +## Application logs + +The application log records messages from the JATOS application. The application logs use a daily log rotation with a history of maximal 30 days. + +Don't confuse the application logs with the [study logs](#study-logs). + +### Application logs path + +The application logs are by default in the JATOS folder under _./logs_. + +1. Via **config file** property `jatos.logs.path` + + ~~~shell + jatos.logs.path = "/my/dir/logs" + ~~~ + +1. Via **command-line** argument `-Djatos.logs.path` + + ~~~shell + -Djatos.logs.path="/my/dir/logs" + ~~~ + +1. Via **environment** variable `JATOS_LOGS_PATH` + + ~~~shell + JATOS_LOGS_PATH="/my/dir/logs" + ~~~ + +### Application logs filename + +By default the logs filename is _application_ (without suffix). + +1. Via **config file** property `jatos.logs.filename` + + ~~~shell + jatos.logs.filename = "myFilename" + ~~~ + +1. Via **command-line** argument `-Djatos.logs.filename` + + ~~~shell + -Djatos.logs.filename="myFilename" + ~~~ + +1. Via **environment** variable `JATOS_LOGS_FILENAME` + + ~~~shell + JATOS_LOGS_FILENAME="myFilename" + ~~~ + +### Application logs appender + +The logs appender can be either `ASYNCSTDOUT` or `ASYNCFILE`. Default is `ASYNCFILE`. If you don't want to record the logs to a file but to _stdout_, change the value to `ASYNCSTDOUT`. + +1. Via **config file** property `jatos.logs.appender` + + ~~~shell + jatos.logs.appender = ASYNCSTDOUT + ~~~ + +1. Via **command-line** argument `-Djatos.logs.appender` + + ~~~shell + -Djatos.logs.appender=ASYNCSTDOUT + ~~~ + +1. Via **environment** variable `JATOS_LOGS_APPENDER` + + ~~~shell + JATOS_LOGS_APPENDER=ASYNCSTDOUT + ~~~ + + +## Study logs + +Every study stored in JATOS has its own study log ([more info](/Study-Log.html)). Among other things, it calculates hashes of result data, which can be CPU-intensive, and on smaller machines it can be better to disable it. + +Don't confuse the study logs with the [application logs](#application-logs). . + +### Enable/disable study logging + +By default study logging is enabled. + +1. Via **config file** property `jatos.studyLogs.enabled` + + ~~~shell + jatos.studyLogs.enabled = false + ~~~ + +1. Via **command-line** argument `-Djatos.studyLogs.enabled` + + ~~~shell + -Djatos.studyLogs.enabled=false + ~~~ + +### Path to study logs + +By default the study logs are stored in the JATOS folder under _./study_logs_. + +1. Via **config file** property `jatos.studyLogs.path` + + ~~~shell + jatos.studyLogs.path = "/path/to/my/jatos_study_logs" + ~~~ + +1. Via **command-line** argument `-Djatos.studyLogs.path` + + ~~~shell + -Djatos.studyLogs.path="/path/to/my/jatos_study_logs" + ~~~ + +1. Via **environment** variable `JATOS_STUDY_LOGS_PATH` + + ~~~shell + JATOS_STUDY_LOGS_PATH="/path/to/my/jatos_study_logs" + ~~~ + + +## Study members + +Allow all users that exist on a JATOS to be added at once as members of a study. Can be useful in small setups, e.g. for a lab installation. Default is `false`. + +1. Via **config file** property `jatos.studyMembers.allowAddAllUsers` + + ~~~shell + jatos.studyMembers.allowAddAllUsers = true + ~~~ + +1. Via **command-line** argument `-Djatos.studyMembers.allowAddAllUsers` + + ~~~shell + -Djatos.studyMembers.allowAddAllUsers=true + ~~~ + + +## Results pagination + +Maximal number of results to be fetched from the DB at once. Default is 10. + +1. Via **config file** property `jatos.maxResultsDbQuerySize` + + ~~~shell + jatos.maxResultsDbQuerySize = 5 + ~~~ + +1. Via **command-line** argument `-Djatos.maxResultsDbQuerySize` + + ~~~shell + -Djatos.maxResultsDbQuerySize=5 + ~~~ + + +## Result data + +Maximum size of the result data of one component run. Default is 5MB. + +1. Via **config file** property `jatos.resultData.maxSize` + + ~~~shell + jatos.resultData.maxSize = 10MB + ~~~ + +1. Via **command-line** argument `-Djatos.resultData.maxSize` + + ~~~shell + -Djatos.resultData.maxSize=10MB + ~~~ + + +## Result file uploading + +During study runs it is possible to upload files to JATOS usually with results. This is an alternative to result data that are stored in the database. It is also possible to download previously uploaded files during a study run. + +### Enable/disable result file uploading + +Default is `true` (enabled). + +1. Via **config file** property `jatos.resultUploads.enabled` + + ~~~shell + jatos.resultUploads.enabled = false + ~~~ + +1. Via **command-line** argument `-Djatos.resultUploads.enabled` + + ~~~shell + -Djatos.resultUploads.enabled=false + ~~~ + +### Path to result files + +The path where JATOS stores the uploaded result files from study runs. By default they are stored in the JATOS folder under _./result_uploads_. + +1. Via **config file** property `jatos.resultUploads.path` + + ~~~shell + jatos.resultUploads.path = "/path/to/my/jatos_result_uploads" + ~~~ + +1. Via **command-line** argument `-Djatos.resultUploads.path` + + ~~~shell + -Djatos.resultUploads.path="/path/to/my/jatos_result_uploads" + ~~~ + +1. Via **environment** variable `JATOS_RESULT_UPLOADS_PATH` + + ~~~shell + JATOS_RESULT_UPLOADS_PATH="/path/to/my/jatos_result_uploads" + ~~~ + +### Max file size + +Specifies the maximum file size per uploaded file. Default is 30MB. + +1. Via **config file** property `jatos.resultUploads.maxFileSize` + + ~~~shell + jatos.resultUploads.maxFileSize = 100MB + ~~~ + +1. Via **command-line** argument `-Djatos.resultUploads.maxFileSize` + + ~~~shell + -Djatos.resultUploads.maxFileSize=100MB + ~~~ + +1. Via **environment** variable `JATOS_RESULT_UPLOADS_MAX_FILE_SIZE` + + ~~~shell + JATOS_RESULT_UPLOADS_MAX_FILE_SIZE=100MB + ~~~ + +### All files size limit per study run + +Specifies the maximum file size of all files together that are uploaded during one study run. Default is 50MB. + +1. Via **config file** property `jatos.resultUploads.limitPerStudyRun` + + ~~~shell + jatos.resultUploads.limitPerStudyRun = 100MB + ~~~ + +1. Via **command-line** argument `-Djatos.resultUploads.limitPerStudyRun` + + ~~~shell + -Djatos.resultUploads.limitPerStudyRun=100MB + ~~~ + +1. Via **environment** variable `JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN` + + ~~~shell + JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB + ~~~ + + +## Superuser + +The _Superuser_ role can be granted to a user and it allows this user to **access ANY study** on this JATOS as if they were a member of this study. This **includes accessing the result data and even deleting the study itself**. This can be useful in small setups, e.g. for a lab installation or if there is a dedicated person responsible for running online studies. Default is `false`. + +If set to `true` an user with the Admin role can grant the role Superuser to any user. + +1. Via **config file** property `jatos.user.role.allowSuperuser` + + ~~~shell + jatos.user.role.allowSuperuser = true + ~~~ + +1. Via **command-line** argument `-Djatos.user.role.allowSuperuser` + + ~~~shell + -Djatos.user.role.allowSuperuser=true + ~~~ + + +## LDAP authentication + +At the moment LDAP users still have to be created manually in JATOS' _User manager_ (with the checkbox LDAP turned on). Only the authentication is done via LDAP. + +If your LDAP server uses encryption, you have to add your certificate to JATOS' trusted certificates defined with `play.ws.ssl.trustManager.stores` (only possible in a config file). E.g., if your certificate's location is in `/jatos/conf/certs/ca.pem`, then use the following to add it: + +``` +play.ws.ssl.trustManager.stores = [ + { type = "PEM", path = "/jatos/conf/certs/ca.pem" } + { path: ${java.home}/lib/security/cacerts, password = "changeit" } +] +``` + +The first line adds your certificate (_type_ can be `PKCS12`, `JKS` or `PEM`). The second line adds Java's default key store. Its default password is "changeit" ([don't change it](https://stackoverflow.com/a/32371148/1278769)). + + +### LDAP URL + +Specifies URL of the LDAP server. Not set or an empty string disables authentication via LDAP. Default is empty (`""`). + +1. Via **config file** property `jatos.user.authentication.ldap.url` + + ~~~shell + jatos.user.authentication.ldap.url = "ldap://my.ldap.org:389" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.ldap.url` + + ~~~shell + -Djatos.user.authentication.ldap.url="ldap://my.ldap.org:389" + ~~~ + +### LDAP base DN + +Specifies the base DN (distinguished name). It can be one DN with a single string (e.g. `"ou=students,dc=example,dc=com"`) or a list of DNs in squared brackets (e.g. `["ou=students,dc=example,dc=com", "ou=scientists,dc=example,dc=com"]`). Not set or an empty string disables authentication via LDAP. Default is empty (`""`). + +1. Via **config file** property `jatos.user.authentication.ldap.basedn` + + ~~~shell + jatos.user.authentication.ldap.basedn = "dc=example,dc=com" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.ldap.basedn` + + ~~~shell + -Djatos.user.authentication.ldap.basedn="dc=example,dc=com" + ~~~ + +### LDAP admin DN and password + +Specifies an DN (distinguished name) and password of an (optional) admin user that has the right to search for other users. Some LDAP servers need this, if it is impossible to bind directly to an _uid_. Not set or an empty string means no admin user is needed. Default is empty (`""`). + +1. Via **config file** properties `jatos.user.authentication.ldap.admin.dn` and `jatos.user.authentication.ldap.admin.password` + + ~~~shell + jatos.user.authentication.ldap.admin.dn = "cn=read-only-admin,dc=example,dc=com" + jatos.user.authentication.ldap.admin.password = "mypassword" + ~~~ + +1. Via **command-line** arguments `-Djatos.user.authentication.ldap.admin.dn` and `-Djatos.user.authentication.ldap.admin.password` + + ~~~shell + -Djatos.user.authentication.ldap.admin.dn="cn=read-only-admin,dc=example,dc=com" + -Djatos.user.authentication.ldap.admin.password="mypassword" + ~~~ + +### LDAP timeout + +Time in milliseconds JATOS waits for a response from your LDAP server. Default is 5000 ms. + +1. Via **config file** property `jatos.user.authentication.ldap.timeout` + + ~~~shell + jatos.user.authentication.ldap.timeout = 10000 + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.ldap.timeout` + + ~~~shell + -Djatos.user.authentication.ldap.timeout=10000 + ~~~ + + +## Google Sign-In + +JATOS users can be authenticated by Google Sign-in. Not set or an empty string disables authentication via Google Sign-In. Default is empty (`""`). + +Specifies the [Google API client ID](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid). + +1. Via **config file** property `jatos.user.authentication.oauth.googleClientId` + + ~~~shell + jatos.user.authentication.oauth.googleClientId = "1234567890-abc123abc123.apps.googleusercontent.com" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oauth.googleClientId` + + ~~~shell + -Djatos.user.authentication.oauth.googleClientId="1234567890-abc123abc123.apps.googleusercontent.com" + ~~~ + + +## OpenID Connect (OIDC) authentication + +(Only in version >= 3.8.5) + +JATOS users can be authenticated by [OIDC sign-in](https://openid.net/developers/how-connect-works/). + +### OIDC discovery URL + +Specifies the OIDC provider's discovery URL. It usually ends in _.well-known/openid-configuration_. + +1. Via **config file** property `jatos.user.authentication.oidc.discoveryUrl` + + ~~~shell + jatos.user.authentication.oidc.discoveryUrl = "http://myOidcProvider/.well-known/openid-configuration" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oidc.discoveryUrl` + + ~~~shell + -Djatos.user.authentication.oidc.discoveryUrl="http://myOidcProvider/.well-known/openid-configuration" + ~~~ + +### OIDC client ID + +Specifies the OIDC client ID. Not set or an empty string disables authentication via OIDC Sign-In. Default is empty (`""`). + +1. Via **config file** property `jatos.user.authentication.oidc.clientId` + + ~~~shell + jatos.user.authentication.oidc.clientId = "myClientId" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oidc.clientId` + + ~~~shell + -Djatos.user.authentication.oidc.clientId="myClientId" + ~~~ + +### OIDC client secret + +Specifies the OIDC client secret. This is optional and can be left empty (`""`). + +1. Via **config file** property `jatos.user.authentication.oidc.clientSecret` + + ~~~shell + jatos.user.authentication.oidc.clientSecret = "myClientSecret" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oidc.clientSecret` + + ~~~shell + -Djatos.user.authentication.oidc.clientSecret="myClientSecret" + ~~~ + +### OIDC ID token signing algorithm + +Specifies the OIDC ID token signing algorithm. Default is `RS256`. + +1. Via **config file** property `jatos.user.authentication.oidc.idTokenSigningAlgorithm` + + ~~~shell + jatos.user.authentication.oidc.idTokenSigningAlgorithm = "ES512" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oidc.idTokenSigningAlgorithm` + + ~~~shell + -Djatos.user.authentication.oidc.idTokenSigningAlgorithm="ES512" + ~~~ + +### OIDC sign-in button text + +Specifies the text of the OIDC sign-in button on the login page. Default is `Sign in with OIDC`. + +1. Via **config file** property `jatos.user.authentication.oidc.signInButtonText` + + ~~~shell + jatos.user.authentication.oidc.signInButtonText = "Sign in with ABC university" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oidc.signInButtonText` + + ~~~shell + -Djatos.user.authentication.oidc.signInButtonText="Sign in with ABC university" + ~~~ + +### OIDC sign-in button logo + +Specifies the URL of a logo that can be used instead of the standard OIDC logo, e.g. a university logo. Default is the OIDC logo. + +1. Via **config file** property `jatos.user.authentication.oidc.signInButtonLogoUrl` + + ~~~shell + jatos.user.authentication.oidc.signInButtonLogoUrl = "http://somedomain/logo.svg" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oidc.signInButtonLogoUrl` + + ~~~shell + -Djatos.user.authentication.oidc.signInButtonLogoUrl="http://somedomain/logo.svg" + ~~~ + +### OIDC success feedback + +Specifies the text of a message that is shown after a successful sign-in. If left empty (`""`) no message is shown. Default is `""`. + +1. Via **config file** property `jatos.user.authentication.oidc.successFeedback` + + ~~~shell + jatos.user.authentication.oidc.successFeedback = "You successfully signed in with ABC university" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.oidc.successFeedback` + + ~~~shell + -Djatos.user.authentication.oidc.successFeedback="You successfully signed in with ABC university" + ~~~ + + +## ORCID (orcid.org) authentication + +(Only in version >= 3.8.5) + +JATOS users can be authenticated by [ORCID sign-in](https://info.orcid.org/documentation/features/public-api/orcid-as-a-sign-in-option-to-your-system/). Internally ORCID uses OpenId Connect. + +### ORCID client ID + +Specifies your ORCID client ID. + +1. Via **config file** property `jatos.user.authentication.orcid.clientId` + + ~~~shell + jatos.user.authentication.orcid.clientId = "APP-ABCDEFGHIJKLMNOP" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.orcid.clientId` + + ~~~shell + -Djatos.user.authentication.orcid.clientId="APP-ABCDEFGHIJKLMNOP" + ~~~ + +### ORCID client secret + +Specifies your ORCID client secret. + +1. Via **config file** property `jatos.user.authentication.orcid.clientSecret` + + ~~~shell + jatos.user.authentication.orcid.clientSecret = "1234abcd-12ab-12ab-12ab-123456abcdef" + ~~~ + +1. Via **command-line** argument `-Djatos.user.authentication.orcid.clientSecret` + + ~~~shell + -Djatos.user.authentication.orcid.clientSecret="1234abcd-12ab-12ab-12ab-123456abcdef" + ~~~ + + +## User password restrictions + +By default JATOS' keeps it simple and relies on the users to choose save passwords: it just enforces a length of at least 7 characters. But this can be changed with the following two properties. + +### Password length + +1. Via **config file** property `jatos.user.password.length` + + ~~~shell + jatos.user.password.length = 8 + ~~~ + +1. Via **command-line** argument `-Djatos.user.password.length` + + ~~~shell + -Djatos.user.password.length=8 + ~~~ + +### Password strength + +Can be one of the following. Default is 0. + +* 0 - No restrictions on characters +* 1 - At least one Latin letter and one number +* 2 - At least one Latin letter, one number and one special character (out of `#?!@$%^&*-`) +* 3 - At least one uppercase Latin letter, one lowercase Latin letter, one number and one special character (out of `#?!@$%^&*-`) + +1. Via **config file** property `jatos.user.password.strength` + + ~~~shell + jatos.user.password.strength = 3 + ~~~ + +1. Via **command-line** argument `-Djatos.user.password.strength` + + ~~~shell + -Djatos.user.password.strength=3 + ~~~ + + +## Database + +See [JATOS with MySQL](JATOS-with-MySQL.html). + +Old style database properties beginning with _db.default_ are deprecated and the new properties beginning with _jatos.db_ should be used instead. + +### Database URL + +1. Via **config file** property `jatos.db.url` + + ~~~shell + jatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" + ~~~ + +1. Via **command-line** argument `-Djatos.db.url` + + ~~~shell + -Djatos.db.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" + ~~~ + +1. Via **environment** variable `JATOS_DB_URL` + + ~~~shell + JATOS_DB_URL="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" + ~~~ + +### Username and password + +1. Via **config file** properties `jatos.db.username` and `jatos.db.password` + + ~~~shell + jatos.db.username = "myusername" + jatos.db.password = "mypassword" + ~~~ + +1. Via **command-line** argument `-Djatos.db.username` and `-Djatos.db.password` + + ~~~shell + -Djatos.db.username = "myusername" -Djatos.db.password = "mypassword" + ~~~ + +1. Via **environment** variable `JATOS_DB_USERNAME` and `JATOS_DB_PASSWORD` + + ~~~shell + JATOS_DB_USERNAME="myusername" + JATOS_DB_PASSWORD="mypassword" + ~~~ + +### Database driver + +For modern MySQL or MariaDB databases this property needs to be set to `com.mysql.cj.jdbc.Driver`. + +1. Via **config file** property `jatos.db.driver` + + ~~~shell + jatos.db.driver = "com.mysql.cj.jdbc.Driver" + ~~~ + +1. Via **command-line** argument `-Djatos.db.driver` + + ~~~shell + -Djatos.db.driver="com.mysql.cj.jdbc.Driver" + ~~~ + +1. Via **environment** variable `JATOS_DB_DRIVER` + + ~~~shell + JATOS_DB_DRIVER="com.mysql.cj.jdbc.Driver" + ~~~ + + +## Multi-node mode + +If you intend to run JATOS on multiple machines in parallel in a cluster you have to set this property to `true`. Default is `false`. + +1. Via **config file** property `jatos.multiNode` + + ~~~shell + jatos.multiNode = true + ~~~ + +1. Via **command-line** argument `-Djatos.multiNode` + + ~~~shell + -Djatos.multiNode = true + ~~~ + + +## User session configuration + +### Timeout + +User session timeout in minutes. Default is 1440 minutes (1 day). + +1. Via **config file** property `jatos.userSession.timeout` + + ~~~shell + jatos.userSession.timeout = 180 + ~~~ + +1. Via **command-line** argument `-Djatos.userSession.timeout` + + ~~~shell + -Djatos.userSession.timeout = 180 + ~~~ + +### Inactivity timeout + +User session timeout after inactivity in minutes. Default is 60 minutes. + +1. Via **config file** property `jatos.userSession.inactivity` + + ~~~shell + jatos.userSession.inactivity = 120 + ~~~ + +1. Via **command-line** argument `-Djatos.userSession.inactivity` + + ~~~shell + -Djatos.userSession.inactivity=120 + ~~~ + +### Secure session + +This property can be used to restrict user access to HTTPS. Default is `false`. + +1. Via **config file** property `play.http.session.secure` + + ~~~shell + play.http.session.secure = true + ~~~ + +1. Via **command-line** argument `-Dplay.http.session.secure` + + ~~~shell + -Dplay.http.session.secure=true + ~~~ + + +## ID cookies + +### Secure ID cookies + +This property can be used to restrict participant access to HTTPS. Sets the ID cookie's _secure_ attribute. Default is `false`. + +1. Via **config file** property `jatos.idCookies.secure` + + ~~~shell + jatos.idCookies.secure = true + ~~~ + +1. Via **command-line** argument `-Djatos.idCookies.secure` + + ~~~shell + -Djatos.idCookies.secure=true + ~~~ + +### _SameSite_ attribute + +Defines the IDCookies' _SameSite_ attribute. Possible values are `None`, `Lax`, or `Strict`. Setting to `Strict` makes the usage of external recruiting tools, like MTurk, impossible. Default is `None`. + +1. Via **config file** property `jatos.idCookies.sameSite` + + ~~~shell + jatos.idCookies.sameSite = "Lax" + ~~~ + +1. Via **command-line** argument `-Djatos.idCookies.sameSite` + + ~~~shell + -Djatos.idCookies.sameSite = "Lax" + ~~~ + + +## PID file location + +Defines the location of the PID file in the file system. + +1. Via **config file** property `play.pidfile.path` + + ~~~shell + play.pidfile.path = "/var/run/jatos.pid" + ~~~ + +1. Via **command-line** argument `-Dplay.pidfile.path` + + ~~~shell + -Dplay.pidfile.path = "/var/run/jatos.pid" + ~~~ + + +## Home page + +### Welcome message + +Specifies a URL that can be used by JATOS to fetch some static HTML. This HTML will then be shown on the home page instead of the default welcome message ([more info](/Customize-JATOS-Home-Page.html)). If left empty (`""`) the default welcome message is shown. Default is empty. + +1. Via **config file** property `jatos.brandingUrl` + + ~~~shell + jatos.brandingUrl = "https://mydomain.com/foobar-university-welcome-page.html" + ~~~ + +1. Via **command-line** argument `-Djatos.brandingUrl` + + ~~~shell + -Djatos.brandingUrl = "https://mydomain.com/foobar-university-welcome-page.html" + ~~~ + +### 'Terms of use' info box + +Specifies a URL link to the 'terms of use' that will be shown in an info box on the home page. If left empty (`""`) the info box is not shown. Default is empty. + +1. Via **config file** property `jatos.termsOfUseUrl` + + ~~~shell + jatos.termsOfUseUrl = "https://mydomain.com/my-terms-of-use.html" + ~~~ + +1. Via **command-line** argument `-Djatos.termsOfUseUrl` + + ~~~shell + -Djatos.termsOfUseUrl = "https://mydomain.com/my-terms-of-use.html" + ~~~ + + +## Study administration page + +Enable/disable some columns in the study administration table. Sometimes the calculation of those columns takes too much time +due to a slow database or file system. + +1. Via **config file** properties `jatos.studyAdmin.showStudyAssetsSize`, `jatos.studyAdmin.showResultDataSize`, and `jatos.studyAdmin.showResultFileSize` + + ~~~shell + jatos.studyAdmin.showStudyAssetsSize = false # Default is true + jatos.studyAdmin.showResultDataSize = true # Default is false + jatos.studyAdmin.showResultFileSize = true # Default is false + ~~~ + +1. Via **command-line** arguments `-Djatos.studyAdmin.showStudyAssetsSize`, `-Djatos.studyAdmin.showResultDataSize`, and `-Djatos.studyAdmin.showResultFileSize` + + ~~~shell + -Djatos.studyAdmin.showStudyAssetsSize = false # Default is true + -Djatos.studyAdmin.showResultDataSize = true # Default is false + -Djatos.studyAdmin.showResultFileSize = true # Default is false + ~~~ + + +## JATOS API + +Enable/disable the JATOS API. By default it is enabled (`true`). + +1. Via **config file** property `jatos.api.allowed` + + ~~~shell + jatos.api.allowed = false + ~~~ + +1. Via **command-line** argument `-Djatos.api.allowed` + + ~~~shell + -Djatos.api.allowed = false + ~~~ diff --git a/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/_category_.json b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/_category_.json new file mode 100644 index 0000000000..2752a1fa3b --- /dev/null +++ b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "References, Configs & JATOS API", + "position": 7 +} diff --git a/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/jatos.js-Reference.md b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/jatos.js-Reference.md new file mode 100644 index 0000000000..8c35b91dfe --- /dev/null +++ b/versioned_docs/version-3.9.1/References_Configs_and_JATOS_API/jatos.js-Reference.md @@ -0,0 +1,2303 @@ +--- +title: jatos.js Reference +slug: /jatos.js-Reference.html +sidebar_position: 1 +--- + +## Introduction + +_jatos.js_ is a JavaScript library that helps you to communicate from your component's JavaScript with your JATOS server. Below we list and describe its variables and functions. + +Always load _jatos.js_ in the `` section with the following line: + +``` + +``` + +All _jatos.js_ variables or functions start with `jatos.`. For example, if you want to get the study's ID you use `jatos.studyId`. + +Most _jatos.js_ variables or functions only work after _jatos.js_ is initialized (`jatos.onLoad()` is used). + +And, please, if you find a mistake or have a question don't hesitate to [contact us](Contact-us.html). + + +## ID variables + +All those IDs are generated and stored by JATOS. _jatos.js_ automatically sets these variables with the corresponding values if you included the `jatos.onLoad()` callback function at the beginning of your JavaScript. + +There's a convenient function that adds most of these IDs to a given object. See function `jatos.addJatosIds(obj)` below. + +### `jatos.studyId` + +ID of the study which is currently running. All the study properties are associated with this ID. + +### `jatos.componentId` + +ID of the component which is currently running. All the component properties are associated with this ID. + +### `jatos.batchId` + +ID of the batch this study run belongs to. All batch properties are associated with this ID. + +### `jatos.workerId` + +Each worker who is running a study has an ID. + +### `jatos.studyCode` + +The study code that was used to start this study run. + +### `jatos.studyResultId` + +This ID is individual for every study run. A study result contains data belonging to the run in general (e.g. Study Session). + +### `jatos.componentResultId` + +This ID is individual for every component in a study run. A component result contains data of the run belonging to the specific component (e.g. result data). + +### `jatos.groupMemberId` + +see [Group Variables](#group-variables) + +### `jatos.groupResultId` + +see [Group Variables](#group-variables) + + +## Study variables + +### `jatos.studyProperties` + +All the properties (except the JSON input data) you entered for this study + +* `jatos.studyProperties.title` - Study's title +* `jatos.studyProperties.uuid` - Study's UUID +* `jatos.studyProperties.description` - Study's description +* `jatos.studyProperties.descriptionHash` - Hash of study's description +* `jatos.studyProperties.locked` - Whether the study is locked or not +* `jatos.studyProperties.dirName` - Study's dir name in the file system of your JATOS installation +* `jatos.studyProperties.groupStudy` - Whether this is a group study or not + +### `jatos.studyJsonInput` + +The JSON input you entered in the study's properties. This is `{}` if the field was left empty. + +### `jatos.studyLength` + +Number of component this study has + + +## Component variables + +### `jatos.componentProperties` + +All the properties (except the JSON input data) you entered for this component + +* `jatos.componentProperties.title` - Component's title +* `jatos.componentProperties.uuid` - Component's UUID +* `jatos.componentProperties.htmlFilePath` - Path to Component's HTML file in your JATOS installation +* `jatos.componentProperties.reloadable` - Whether it's reloadable + +### `jatos.componentJsonInput` + +The JSON input you entered in the component's properties. This is `{}` if the field was left empty. + +### `jatos.componentList` + +An array of all components of this study with basic information about each component. For each component it has the `title`, `id`, whether it is `active`, and whether it is `reloadable`. + +### `jatos.componentPos` + +Position of this component within the study starting with 1 (like shown in the GUI) + + +## Other variables + +### `jatos.version` + +Current version of the _jatos.js_ library + +### `jatos.urlQueryParameters` + +Original query string parameters of the URL that starts the study. It is provided as a JavaScript object; the value is `{}` if no query string parameters are present. This might be useful to pass on information from outside of JATOS into a study run, e.g. if you want to pass on information like gender and age. However if you know the information beforehand it's easier to put them in the Study's or Component's JSON input. Another example is MTurk which passes on it's worker's ID via a URL query parameter. + +**Examples** + +1. One has this study link: + + `http://localhost:9000/publix/uXU9eYJpWdg` + + Now one could add parameters to the URL's query string to pass on external information into the study run. E.g. the following URL would add the parameters 'foo' with the value 'bar' and 'a' with the value '123': + + `http://localhost:9000/publix/uXU9eYJpWdg?foo=bar&a=123` + + Then those parameter will be accessible during the study run as `jatos.urlQueryParameters.a` and `jatos.urlQueryParameters.foo`. + +1. MTurk uses for its worker ID the URL query parameter 'workerId' and this is accessible via `jatos.urlQueryParameters.workerId`. + + +### `jatos.studySessionData` + +The session data variable can be accessed and modified by every component of a study. It's a very convenient way to share data between different components. Whatever is written in this variable will be available in the subsequent components. However, remember that the session data will be deleted after the study is finished (see also [Session Data - Three Types](Session-Data-Three-Types.html)). + +### `jatos.channelSendingTimeoutTime` + +Time in ms to wait for an answer after sending a message via a channel (batch or group). Set this variable if you want to change the default value (default is 10 s). + +**Example** + +```javascript +jatos.channelSendingTimeoutTime = 20000; // Sets channel timeout to 20 seconds +``` + +### `jatos.channelHeartbeatInterval` + +Waiting time in ms between channel (group or batch) heartbeats (default is 25 s) + +**Example** + +```javascript +jatos.channelHeartbeatInterval = 10000; // Sets interval to 10 seconds +``` + +### `jatos.channelHeartbeatTimeoutTime` + +Waiting time in ms for JATOS server's answer to a channel heartbeat (default is 10 s) + +**Example** + +```javascript +jatos.channelHeartbeatTimeoutTime = 20000; // Sets interval to 20 seconds +``` + +### `jatos.channelClosedCheckInterval` + +Waiting time in ms between checking if channels (group or batch) are closed unexpectedly (default is 2 s) + +**Example** + +```javascript +jatos.channelClosedCheckInterval = 4000; // Sets interval to 4 seconds +``` + +### `jatos.channelOpeningBackoffTimeMin` + +Min waiting time (in ms) between channel reopening attempts (default is 1s for min and 2 min for max). _jatos.js_ uses an _exponential back-off_ retry pattern for the channels. + +**Example** + +```javascript +jatos.channelOpeningBackoffTimeMin = 2000; // Sets interval to 2 seconds +``` + +### `jatos.channelOpeningBackoffTimeMax` + +Max waiting time (in ms) between channel reopening attempts (default is 1s for min and 2 min for max). _jatos.js_ uses an _exponential back-off_ retry pattern for the channels. + +**Example** + +```javascript +jatos.channelOpeningBackoffTimeMax = 60000; // Sets interval to 1 minute +``` + +### `jatos.httpTimeout` + +Time in ms to wait for an answer of an HTTP request by _jatos.js_. Set this variable if you want to change the default value (default is 1 min). + +**Example** + +```javascript +jatos.httpTimeout = 30000; // Sets HTTP timeout to 30 seconds +``` + +### `jatos.httpRetry` + +Some jatos functions (e.g. `jatos.sendResultData`) send a request to the JATOS server. If this request was not successful (e.g. network problems) _jatos.js_ retries it. With this variable one can change the number of retries. The default is 5. + +**Example** + +```javascript +jatos.httpRetry = 2; // Attempts 2 retries of failed requests +``` + +### `jatos.httpRetryWait` + +Same as `jatos.httpRetry` but this variable defines the waiting time between the retries. The default is 1000 ms. + +**Example** + +```javascript +jatos.httpRetryWait = 5000; // Sets retry waiting time to 5 seconds +``` + +### `jatos.waitSendDataOverlayConfig` + +Config of the overlay that is shown when the component ended but there are still data to be sent. See function jatos.showOverlay for config options. By default the text is "Sending data. Please wait." with an image of a spinning wheel. + +**Example** + +```javascript +jatos.waitSendDataOverlayConfig = { text: "Enviando datos. Espere." }; +``` + + + +## General _jatos.js_ functions + +### `jatos.onLoad` + +Defines callback function that _jatos.js_ will call when it's finished initialising. + +* _@param {function} callback_ - function to be called after _jatos.js_' initialization is done + +**Example** + +```javascript +jatos.onLoad(function() { + // Start here with your code that uses jatos.js' variables and functions +}); +``` + + +### `jatos.addAbortButton` + +Adds a button to the document that if pressed calls _jatos.abortStudy_ (which cancels the study run and deletes all result data and files). By default this button is in the bottom-right corner but this and other properties can be configured. + +* _@param {object optional} config_ - Config object + * _@param {string optional} text_ - Button text (Default: 'Cancel') + * _@param {boolean optional} confirm_ - Should the worker be asked for confirmation? (Default: true) + * _@param {string optional} confirmText_ - Confirmation text (Default: 'Do you really want to cancel this study?') + * _@param {string optional} tooltip_ - Tooltip text (Default: 'Cancels this study and deletes all already submitted data') + * _@param {string optional} msg_ - Message to be send back to JATOS to be logged (Default: 'Worker decided to abort') + * _@param {string optional} style_ - Additional CSS styles + * _@param {function optional} action_ - Which function should be called in the end. Default is jatos.abortStudy. + +**Examples** + +1. Adds the default cancel button + + ```javascript + jatos.addAbortButton() + ``` + +1. Adds a cancel button and changes some properties + + ```javascript + jatos.addAbortButton({ + text: "Quit", + confirmText: "You really wanne quit?", + tooltip: "Don't you dare clicking here!", + msg: "This worker aborted the mission.", + style: "color:green" + }); + ``` + +1. Adds a cancel button and changes the position to the bottom-left + + ```javascript + jatos.addAbortButton({ + style: "left:1em; right:unset" + }); + ``` + +1. Adds a cancel button and changes the position to the top-right + + ```javascript + jatos.addAbortButton({ + style: "top:1em; bottom:unset" + }); + ``` + +1. Adds a cancel button and calls 'myFunction' if pressed + + ```javascript + jatos.addAbortButton({ + action: myFunction + }); + ``` + + +### `jatos.showBeforeUnloadWarning` + +Convenience function that adds or cancels a warning popup that will be shown by the browser to the worker who attempts to reload the page or close the browser (tab). By default this is turned on for components that are not 'reloadable'. Modern browsers do not allow to change the message of this popup. This works only if at least one user action happend in the window, e.g. mouse click (https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event). + +* _@param {boolean} show_ - If true the warning will be shown - if false a previously added warning will be canceled + +**Example** + +Adds a warning popup: + +```javascript +jatos.showBeforeUnloadWarning(true); +``` + + +### `jatos.showOverlay` + +Convenience function that shows a text and an image in the center of the screen. By default the text is 'Please wait.' and the image is an spinning wheel. + +* _@param {object optional} config_ - Config object + * _@param {string optional} text_ - Text to be shown. Default is "Please wait". + * _@param {string optional} imgUrl_ - URL of the image. Default is a spinning wheel. + * _@param {string optional} showImg_ - If true the image is shown - otherwise not. Default is true. + * _@param {string optional} style_ - Additional CSS styles + +**Examples** + +1. Shows the default overlay with 'Please wait.' and an spinning wheel. + + ```javascript + jatos.showOverlay() + ``` + +1. Shows text only + + ```javascript + jatos.showOverlay({ + text: "Please have a coffee break for 5 minutes", + showImg: false + }); + ``` + +1. Shows text only + + ```javascript + jatos.showOverlay({ + text: "Please have a coffee break for 5 minutes", + imgUrl: "http://url-to-my-coffee-picture", + style: "color:brown" + }); + ``` + +### `jatos.removeOverlay` + +Removes an overlay that was added by jatos.showOverlay. + +**Example** + +```javascript +jatos.removeOverlay() +``` + + +### `jatos.onError` + +DEPRECATED - use the specific function's error callback or Promise function instead + +Defines a callback function that is to be called in case _jatos.js_ produces an error. + +* _@param {function} callback_ - Function to be called in case of an error + +**Example** + +Show the error message in an alert box: + +```javascript +jatos.onError(alert); +``` + + +### `jatos.log` + +Sends a message to be logged back to the JATOS server where it will be logged in JATOS' log file. + +* _@param {string} logMsg_ - The messages to be logged + +**Example** + +```javascript +jatos.log("Log this message in JATOS' log file"); +``` + + +### `jatos.catchAndLogErrors` + +Convenience function that sends all 'error' and 'unhandledrejection' events and 'console.error' and 'console.warn' calls to [JATOS' server log](Troubleshooting.html#read-log-file-in-the-browser). This is useful in debugging. + +**Example** + +```javascript +jatos.catchAndLogErrors(); +``` + + +### `jatos.addJatosIds` + +Convenience function that adds some [IDs](jatos.js-Reference.html#ids) (study code, study ID, study title, batch ID, batch title, component ID, component position, component title, worker ID, study result ID, component result ID, group result ID, group member ID) to the given object. + +* _@param {object} obj_ - Object to which the IDs will be added + +**Example** + +```javascript +var resultData = {}; +jatos.addJatosIds(resultData); +``` + + +### `jatos.setHeartbeatPeriod` + +Every running component sends regularly a HTTP request (the heartbeat) back to the JATOS server. This signals that it is still running. As soon as the browser tab running the component is closed the heartbeat ceases. The time of the last heartbeat is visible in the GUI, in the study results page in the 'Last Seen' row. This way you can easily see if a worker is still running your study or if (and when) he abandonend it. By default the heartbeat period is 2 minutes. By careful not to set the period too low (few seconds or even milliseconds) since it might overload your network or your JATOS server. + +* _@param {number} heartbeatPeriod_ - Time period between two heartbeats in milliseconds + +**Example** + +```javascript +jatos.setHeartbeatPeriod(60000); // Sets to a heartbeat every minute +``` + + +### `jatos.setStudySessionData` + +**If you want to just write into the study session, this function is not what you need.** If you want to write something into the study session, just write into the [`jatos.studySessionData`](jatos.js-Reference.html#studys-session-data) object. + +Posts Study Session data to the JATOS server. This function sets the study session data and **sends it to the JATOS server for safe storage**. This is done automatically whenever a component finishes. But sometimes it is necessary to trigger this manually, e.g. in a very long-running component one might want to store the session intermediately. It offers callbacks, either as parameters or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the transfer. + +* _@param {object} sessionData_ - object to be submitted +* _@param {optional function} onSuccess_ - Function to be called after this function is finished +* _@param {optional function} onFail_ - Function to be called after if this this functions fails +* _@return {Promise}_ + +**Example** + +```javascript +var studySessionData = { "a": 123, "b": 789, "c": 100}; +jatos.setStudySessionData(studySessionData); +``` + + +## Functions to control study flow + +### `jatos.startComponent` + +Finishes the currently running component and starts the component with the given ID or UUID. Though often it's better to use `jatos.startComponentByPos` instead because it keeps working even after an export/import of the study into another JATOS. One can additionally send result data back to the JATOS server. + +There are two versions: with or without message + +1. Without message: + * _@param {number} componentIdOrUuid_ - ID or UUID of the component to start + * _@param {optional object} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional function} onError_ - Callback function if fail + +1. With message: + * _@param {number} componentIdOrUuid_ - ID or UUID of the component to start + * _@param {optional object} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional string} message_ - Message that should be logged (max 255 chars) + * _@param {optional function} onError_ - Callback function if fail + +**Examples** + +1. Jump to component with ID 23 + + ```javascript + jatos.startComponent(23); + ``` + +1. Jump to component by using its UUID + + ```javascript + jatos.startComponent("3d277289-754b-4fd6-aa76-c8404deda02e"); + ``` + +1. Send result data and jump to another component + + ```javascript + var resultData = "my important result data"; + jatos.startComponent(23, resultData); + ``` + +1. Send result data, jump to another component and send a message back that will be visible in JATOS result pages and log + + ```javascript + var resultData = "my important result data"; + jatos.startComponent(23, resultData, "everything okay"); + ``` + + +### `jatos.startComponentByPos` + +Finishes the currently running component and starts the component with the given position. The component position is the count of the component within the study like shown in the study overview page (1st component has position 1, 2nd component position 2, ...). One can additionally send result data back to the JATOS server. + +There are two versions: with or without message + +1. Without message + + * _@param {number} componentPos_ - Position of the component to start + * _@param {optional object} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional function} onError_ - Callback function if fail + +1. With message + + * _@param {number} componentPos_ - Position of the component to start + * _@param {optional object or string} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional string} message_ - Message that should be logged (max 255 chars) + * _@param {optional function} onError_ - Callback function if fail + +**Examples** + +1. Jump to component in position 3 + + ```javascript + jatos.startComponentByPos(3); + ``` + +1. Send result data and jump to component with position 3 + + ```javascript + var resultData = "my important result data"; + jatos.startComponentByPos(3, resultData); + ``` + +1. Send result data, jump to component in position 3 and send a message back that will be visible in JATOS result pages and log + + ```javascript + var resultData = "my important result data"; + jatos.startComponentByPos(3, resultData, "everything okay"); + ``` + + +### `jatos.startComponentByTitle` + +(Needs JATOS version >= 3.7.5) - Finishes the currently running component and starts the component with the given title. If there is more than one component with this title it starts the first. One can additionally send result data back to the JATOS server. + +There are two versions: with or without message + +1. Without message + + * _@param {string} title - Title of the component to start + * _@param {optional object} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional function} onError_ - Callback function if fail + +1. With message + + * _@param {string} title - Title of the component to start + * _@param {optional object or string} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional string} message_ - Message that should be logged (max 255 chars) + * _@param {optional function} onError_ - Callback function if fail + +**Examples** + +1. Jump to component with title "Some title" + + ```javascript + jatos.startComponentByTitle("Some title"); + ``` + +1. Send result data and jump to component with title "Some title" + + ```javascript + var resultData = "my important result data"; + jatos.startComponentByTitle("Some title", resultData); + ``` + +1. Send result data, jump to component with title "Some title" and send a message back that will be visible in JATOS result pages and log + + ```javascript + var resultData = "my important result data"; + jatos.startComponentByTitle("Some title", resultData, "everything okay"); + ``` + + +### `jatos.startNextComponent` + +Finishes the currently running component and starts the next component of this study. The next component is the one with position + 1. The component position is the count of the component within the study like shown in the study overview page (1st component has position 1, 2nd component position 2, ...). One can additionally send result data back to the JATOS server. + +There are two versions: with or without message + +1. Without message + + * _@param {optional object} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional function} onError_ - Callback function if fail + +1. With message + + * _@param {optional object or string} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional string} message_ - Message that should be logged (max 255 chars) + * _@param {optional function} onError_ - Callback function if fail + +**Examples** + +1. Jump to the next component + + ```javascript + jatos.startNextComponent(); + ``` + +1. Send result data and jump to the next component + + ```javascript + var resultData = "my important result data"; + jatos.startNextComponent(resultData); + ``` + +1. Send result data, jump to the next component and send a message back that will be visible in JATOS result pages and log + + ```javascript + var resultData = "my important result data"; + jatos.startNextComponent(resultData, "everything okay"); + ``` + + +### `jatos.startLastComponent` + +Finishes the current component and starts the last component of this study. If the last component is inactive it starts the component with the highest position that is active. The component position is the count of the component within the study like shown in the study overview page (1st component has position 1, 2nd component position 2, ...). One can additionally send result data back to the JATOS server. + +There are two versions: with or without message + +1. Without message + + * _@param {optional object} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional function} onError_ - Callback function if fail + +1. With message + + * _@param {optional object or string} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). + * _@param {optional string} message_ - Message that should be logged (max 255 chars) + * _@param {optional function} onError_ - Callback function if fail + +**Examples** + +1. Jump to the last component + + ```javascript + jatos.startLastComponent(); + ``` + +1. Send result data and jump to the last component + + ```javascript + var resultData = "my important result data"; + jatos.startLastComponent(resultData); + ``` + +1. Send result data, jump to the last component and send a message back that will be visible in JATOS result pages and log + + ```javascript + var resultData = "my important result data"; + jatos.startLastComponent(resultData, "everything okay"); + ``` + + +### `jatos.abortStudy` + +**Hint**: There is a convenience function `jatos.addAbortButton` that already adds a button to your document including showing an confirmation box and options to change it to your needs. + +Aborts study. All previously submitted result data will be deleted. Afterwards the worker is redirected to the study end page. Data stored in the Batch Session or Group Session are unaffected by this. + +* _@param {optional string} message_ - Message that will be stored together with the study results and is accessible via JATOS' GUI result pages. The message can be max 255 characters long. +* _@param {optional boolean} showEndPage_ - If 'true' an end page is shown - if 'false' it behaves like `jatos.endStudyAjax`, which means no showing of JATOS' end page + +**Examples** + +1. Just abort study + + ```javascript + jatos.abortStudy(); + ``` + +1. Additionally send a message + + ```javascript + jatos.abortStudy("participant aborted by pressing abort button"); + ``` + + +### `jatos.abortStudyAjax` + +**Hint**: There is a convenience function `jatos.addAbortButton` that already adds a button to your document including showing an confirmation box and options to change it to your needs. + +Aborts study with an Ajax call. All previously submitted result data will be deleted. Data stored in the Batch Session or Group Session are unaffected by this. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the ending. + +* _@param {optional string} message_ - Message that should be logged +* _@param {optional function} onSuccess_ - Function to be called in case of successful submit +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Examples** + +1. Just abort study + + ```javascript + jatos.abortStudyAjax(); + ``` + +1. Abort study with a message that will be sent back to JATOS and shown in the result page and put in the log + + ```javascript + jatos.abortStudyAjax("Worker clicked Abort button"); + ``` + + +### `jatos.endStudy` + +Ends study. Redirects the worker to study's end page afterwards. + +There are two versions: with and without result data + +1. With result data + * _@param {optional string or object} resultData_ - Result data to be sent back to the JATOS server + * _@param {optional boolean} successful_ - 'true' if study should finish successfully, 'false' otherwise. Default is true + * _@param {optional string} message_ - Message that will be stored together with the study results and is accessible via JATOS' GUI result pages. The message can be max 255 characters long + * _@param {optional boolean} showEndPage_ - If 'true' an end page is shown - if 'false' it behaves like `jatos.endStudyAjax`, which means no showing of JATOS' end page + +1. Without result data + * _@param {optional boolean} successful_ - 'true' if study should finish successfully, 'false' otherwise. Default is true + * _@param {optional string} message_ - Message that will be stored together with the study results and is accessible via JATOS' GUI result pages. The message can be max 255 characters long + * _@param {optional boolean} showEndPage_ - If 'true' an end page is shown - if 'false' it behaves like `jatos.endStudyAjax`, which means no showing of JATOS' end page + +**Examples** + +1. Just end study + + ```javascript + jatos.endStudy(); + ``` + +1. End study and send a message back that will be visible in JATOS result pages and log + + ```javascript + jatos.endStudy(true, "everything worked fine"); + ``` + +1. Indicate a failure - leads to study result state FAIL + + ```javascript + jatos.endStudy(false, "internal JS error"); + ``` + +1. Send result data and end study + + ```javascript + var resultData = {id: 123, data: "my important result data"}; + jatos.endStudy(resultData); + ``` + +1. Send result data, end study and send a message back that will be visible in JATOS result pages and log + + ```javascript + var resultData = {id: 123, data: "my important result data"}; + jatos.endStudy(resultData, true, "everything worked fine"); + ``` + + +### `jatos.endStudyAndRedirect` + +Ends study and redirects the given URL. This is useful if you want to let the worker return to a recruitment platform (e.g. Prolific) or have your own end page. The same effect can be achieved with the Study Properties' _End Redirect URL_ field. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the ending. + +**Hint**: There is a '**End Redirect URL**' field in the Study Properties that also specifies the redirect URL. It's easier to use, but not as flexible. + +* _@param {string} url_ - URL of the page to be redirected to after the study run was successfully finished +* _@param {optional boolean} successful_ - 'true' if study should finish successful - 'false' otherwise. +* _@param {optional string} message_ - Message that will be stored together with the study results and is accessible via JATOS' GUI result pages. The message can be max 255 characters long. +* _@param {optional function} onSuccess_ - Function to be called in case of successful submit +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Examples** + +1. End study and redirect afterwards + + ```javascript + jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD"); + ``` + +1. End study and redirect afterwards. Send result data. + + ```javascript + var resultData = {id: 123, data: "my important result data"}; + jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData); + ``` + +1. End study and redirect afterwards. A message will be sent back to JATOS and shown in the result page and put in the log. + + ```javascript + jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", true, "everything worked fine"); + ``` + +1. End study and indicate a failure and send a message. Does not redirect. + + ```javascript + jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", false, "internal JS error"); + ``` + + +### `jatos.endStudyAjax` + +Ends study with an Ajax call - afterwards the study is not redirected to the JATOS' end page. If the study was run by an MTurk worker the confirmation code will be in the response. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the ending. + +* _@param {optional boolean} successful_ - 'true' if study should finish successful - 'false' otherwise. +* _@param {optional string} message_ - Message that will be stored together with the study results and is accessible via JATOS' GUI result pages. The message can be max 255 characters long. +* _@param {optional function} onSuccess_ - Function to be called in case of successful submit +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Examples** + +1. Just end study + + ```javascript + jatos.endStudyAjax(); + ``` + +1. End study with a message that will be sent back to JATOS and shown in the result page and put in the log + + ```javascript + jatos.endStudyAjax(true, "everything worked fine"); + ``` + +1. Indicate a failure and send a message + + ```javascript + jatos.endStudyAjax(false, "some error description"); + ``` + +1. End study and show the confirmation code to the MTurk worker + + ```javascript + jatos.endStudyAjax().then((confirmationCode) => { + // Show the confirmation code to the worker + }); + ``` + +1. Use Promise to submit result data and afterwards, end the study and move to another URL ([see also](jatos.js-Reference.html#jatosendstudyandredirect)) + + ```javascript + var resultData = {id: 123, data: "my important result data"}; + jatos.submitResultData(resultData) + .then(jatos.endStudyAjax) + .then(() => { window.location.href = 'http://example.com/index.html' }) + .catch(() => console.log("Something went wrong")); + ``` + +1. Send result data and end study + + ```javascript + var resultData = {id: 123, data: "my important result data"}; + jatos.endStudyAjax(resultData); + ``` + + +## Result data and result upload/download files + +### `jatos.submitResultData` + +Posts result data for the currently running component back to the JATOS server. Already stored result data for this component will be **overwritten**. If you want to append result data use `jatos.appendResultData` instead. Alternatively you can send result data with functions that jump to another component (e.g. `jatos.startComponent`) or end the study (`jatos.endStudy`). It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the transfer. + +* _@param {object} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON. +* _@param {optional function} onSuccess_ - Function to be called in case of successful submit +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Examples** + +1. Send result data back to the JATOS server + + ```javascript + var resultData = {"a": 123, "b": 789, "c": 100}; + jatos.submitResultData(resultData); + ``` + +1. It's often used together with `jatos.startNextComponent` to first submit result data back to the JATOS server and afterwards jump to the next component + + ```javascript + var resultData = {"a": 123, "b": 789, "c": 100}; + jatos.submitResultData(resultData, jatos.startNextComponent); + ``` + + +1. Or together with `jatos.startComponentByPos` to start a particular component (here at position 4) + + ```javascript + var resultData = {"a": 123, "b": 789, "c": 100}; + jatos.submitResultData(resultData, () => { jatos.startComponentByPos(4) }); + ``` + +1. Or by using the returned Promise + + ```javascript + var resultData = {"a": 123, "b": 789, "c": 100}; + jatos.submitResultData(resultData) + .then(() => console.log('success')) + .catch(() => console.log('error')); + ``` + + +### `jatos.appendResultData` + +Appends result data to the already posted result data. Contrary to `jatos.submitResultData` it does not overwrite the result data. Alternatively you can send result data with functions that jump to another component (e.g. `jatos.startComponent`) or end the study (`jatos.endStudy`). It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the transfer. This function can be used several times during an component run to incrementally save result data. + +* _@param {string} resultData_ - String or object that will be sent as result data. An object will be serialized to JSON (stringify). +* _@param {optional function} onSuccess_ - Function to be called in case of successful submit +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Examples** + +1. Append result data to the already sent + + ```javascript + var resultData = { "a": 123, "b": 789, "c": 100 }; + jatos.appendResultData(resultData); + ``` + +1. Use mulitple `jatos.appendResultData` in a row + + ```javascript + jatos.appendResultData({"a": 1}) + .then(() => jatos.appendResultData({"b": 2})) + .then(() => jatos.appendResultData({"c": 3})) + .catch(() => console.log('Something went wrong')); + ``` + +1. You can use it together with `jatos.startNextComponent` to first append result data and afterwards jump to the next component + + ```javascript + var resultData = { "a": 123, "b": 789, "c": 100}; + jatos.appendResultData(resultData, jatos.startNextComponent); + ``` + +1. Or by using the returned Promise + + ```javascript + var resultData = {"a": 123, "b": 789, "c": 100}; + jatos.appendResultData(resultData) + .then(() => jatos.startNextComponent()) + .catch(() => console.log('Something went wrong')); + ``` + +1. Or together with `jatos.startComponentByPos` to start a particular component (here at position 4) + + ```javascript + var resultData = {"a": 123, "b": 789, "c": 100}; + jatos.appendResultData(resultData) + .then(() => jatos.startComponentByPos(4)) + .catch(() => console.log('Something went wrong')); + ``` + + +### `jatos.uploadResultFile` + +Uploads a file to the JATOS server where they are stored in the server's file system (but not in the database). Similar to result data it can be downloaded in the JATOS UI, in the result pages. The files are stored per component - that means you can use the same filename without overwriting the file if the upload happens from different components. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the transfer. + +* _@param {Blob, string or object} obj_ - Data to be uploaded as a file. Can be [Blob](https://developer.mozilla.org/en-US/docs/Web/API/Blob), a string, or a object. A Blob will be uploaded right away. A string is turned into a Blob. An object is first turned into a JSON string and then into a Blob. +* _@param {string} filename_ - Name of the uploaded file +* _@param {optional function} onSuccess_ - Function to be called in case of success +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Examples** + +1. Upload text + + ```javascript + jatos.uploadResultFile("this is my data", "example.txt") + .then(() => console.log("File was successfully uploaded")) + .catch(() => console.log("File upload failed")); + ``` + +1. Upload object as JSON + + ```javascript + var resultData = { "a": 123, "b": 789, "c": 100}; + jatos.uploadResultFile(resultData, "example.json") + .then(() => console.log("File was successfully uploaded")) + .catch(() => console.log("File upload failed")); + ``` + +1. Upload text as Blob + + ```javascript + var blob = new Blob(["Hello, world!"], {type: 'text/plain'}); + jatos.uploadResultFile(blob, "example.txt") + .then(() => console.log("File was successfully uploaded")) + .catch(() => console.log("File upload failed")); + ``` + +1. Turn canvas into Blob and upload as image file. It assumes you have an canvas element with ID 'canvas'. + + ```javascript + var canvas = document.getElementById('canvas'); + canvas.toBlob((blob) => { + jatos.uploadResultFile(blob, "canvas.png") + .then(() => console.log("File was successfully uploaded")) + .catch(() => console.log("File upload failed")); + }); + ``` + +1. For more real-world examples have a look at the ['Drawing' and the 'Video Recording' examples](/Example-Studies) + + +### `jatos.downloadResultFile` + +Downloads a file from the JATOS server. One can only download a file that was previously uploaded with `jatos.uploadResultFile` in the same study run. If the file contains text it returns the content as a string. If the file contains JSON, it returns the JSON already parsed as an object. All other [MIME types](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) are returned as a Blob. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the transfer. + +* _@param {string} filename_ - Name of the uploaded file +* _@param {optional function} onSuccess_ - Function to be called in case of success +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +Additionally you can specify the component position from where the file was uploaded (in case different components uploaded files with the same filename) + +* _@param {number} componentPos_ - Position of the component where the file was uploaded +* _@param {string} filename_ - Name of the uploaded file +* _@param {optional function} onSuccess_ - Function to be called in case of success +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Examples** + +1. Download text file + + ```javascript + jatos.downloadResultFile("example.txt") + .then((text) => console.log(text)) + .catch(() => console.log("File download failed")); + ``` + +1. Download JSON file + + ```javascript + jatos.downloadResultFile("example.json") + .then((obj) => console.log(JSON.stringify(obj))) + .catch(() => console.log("File download failed")); + ``` + +1. Download image and display it in a canvas element + + ```javascript + jatos.downloadResultFile("canvas.png") + .then((blob) => { document.getElementById("canvas").src = URL.createObjectURL(blob) }) + .catch(() => console.log("File download failed")); + ``` + +1. Download file and specify that the file was uploaded in the first component + + ```javascript + jatos.downloadResultFile(1, "example.txt") + .then((text) => console.log(text)) + .catch(() => console.log("File download failed")); + ``` + +1. For more real-world examples have a look at the ['Drawing' and the 'Video Recording' examples](/Example-Studies) + + + +## Batch variables + +### `jatos.batchProperties` + +All the properties you entered for this batch. + + * `jatos.batchProperties.allowedWorkerTypes` - List of worker types that are currently allowed to run in this batch. + * `jatos.batchProperties.maxActiveMembers` - How many members a group can have at the same time + * `jatos.batchProperties.maxTotalMembers` - How many members a group is allowed to have at the same time + * `jatos.batchProperties.maxTotalWorkers` - Total amount of workers a group is allowed to have altogether in this batch + * `jatos.batchProperties.title` - Title of this batch + +### `jatos.batchJsonInput` + +The JSON input you entered in the batch's properties. This is `{}` if the field was left empty. + + + +## Batch Session functions + +The Batch Session is stored in JATOS' database on the server side (see also [Session Data - Three Types](Session-Data-Three-Types.html)). That means that all changes in the Batch Session have to be synchronized between the client and the server. This is done via the batch channel. Therefore all writing functions (`add`, `remove`, `clear`, `replace`, `copy`, `move`, `set`, `setAll`) can be paired with callback functions that will signal success or failure in the client-server sync. These callback functions can be either passed as parameters to `jatos.batchSession.[function_name]` or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +On the other side for all reading functions (`get`, `find`, `getAll`, `test`) there is no need to sync data between client and server, because _jatos.js_ keeps a copy of the Batch Session locally. Therefore all reading functions do not offer callbacks, because there is no risk of failure of synchronization. + +Additionally to the reading and writing functions the calback function `jatos.onBatchSession(callback)` offers a way to get notified whenever the Batch Session changes in the JATOS' database regardless of the origin of the change. This way, you can have the client of each worker react to changes in the batch that were done by another worker in the batch. + +Accessing the Batch Session is done via [JSON Patches (RFC 6902)](https://tools.ietf.org/html/rfc6902) and +[JSON Pointer (RFC 6901)](https://tools.ietf.org/html/rfc6901). An introduction can be found under [jsonpatch.com](http://jsonpatch.com/). For JSON Patches _jatos.js_ uses the [JSON-Patch](https://github.com/Starcounter-Jack/JSON-Patch) library from Joachim Wester and for JSON Pointers the [jsonpointer.js](https://github.com/alexeykuzmin/jsonpointer.js) library from Alexey Kuzmin. + + +### `jatos.onBatchSession` + +Defines a callback function that is called every time the Batch Session changes on the JATOS server side (that includes updates in the session originating from other workers that run the study in parallel). + +The callback function has two parameter: +* _@param {string} path_ - JSON pointer to the changed field in the Batch Session +* _@param {string} op_ - JSON patch operation ('add', 'remove', 'clear', ...) that was applied + +**Examples** + +1. Log whenever something changes in the Batch session + + ```javascript + jatos.onBatchSession(function(path, op){ + console.log("Batch Session was updated in path " + path + " with operation " + op); + }); + ``` + +1. `onBatchSession` is often used together with `jatos.batchSession.find` to get the updated value: + + ```javascript + jatos.onBatchSession(function(path){ + var changedObj = jatos.batchSession.find(path); + console.log("The changed object is " + JSON.stringify(changedObj)); + }); + ``` + + +### `jatos.batchSession.get` + +Convenience function: like `jatos.batchSession.find` but works with a key instead of a JSON Pointer. Therefore it works only on the first level of the session's object tree. It takes a name of a field within the Batch Session and returns the matching value, or `undefined` if the key does not exist. For all other levels of the object tree use `jatos.batchSession.find`. Gets the object from the locally stored copy of the session and does not call the server. + +* _@param {string} name_ - name of the field +* _@return {object}_ - the value that is stored under name + +**Examples** + +1. Get the value that belongs to a key in the Batch Session + + If the Batch Session is `{"a": 1000, "b": "watermelon"}` + + ```javascript + // Since the parameter is the key's name and not a path it does not start with a "/" + var b = jatos.batchSession.get("b"); // b is "watermelon" + var c = jatos.batchSession.get("c"); // c is undefined + ``` + +1. With `jatos.batchSession.get` you can only access the first level of the object tree - if you want another level use `jatos.batchSession.find`. If the Batch Session is `{"a": {"a1": 123, "a2": "watermelon"}}` + + ```javascript + var a1 = jatos.batchSession.get("a1"); // a1 is undefined !!! + var a = jatos.batchSession.get("a"); // a is { "a1": 123, "a2": "watermelon" } + ``` + + +### `jatos.batchSession.set` + +A convenience function for `jatos.batchSession.add`. Instead of a JSON Pointer path it accepts a name of the field to be stored (without a slash in front). Therefore it works only on the first level of the Batch Session's object tree. If the name already exists in the Batch Session the value will be overwritten. + +* _@param {string} name_ - name of the field +* _@param {object} value_ - value to be stored +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Set a key and its value in the Batch Session + + If the Batch Session is `{"a": 1234}` + + ```javascript + // Since the parameter is the key's name and not a path it does not start with a "/" + var b = jatos.batchSession.set("b", "koala"); + ``` + + then after the Batch Session is successfully updated the new object is `{"a": 1234, "b": "koala"}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.batchSession.set("b", "koala") + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + +1. Have a series of Batch Session changes + + ```javascript + jatos.batchSession.set("a", 1) + .then(() => jatos.batchSession.set("b", 2)) + .then(() => jatos.batchSession.set("c", 3)) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSession.getAll` + +Returns the complete Batch Session data. Gets the object from the locally stored copy of the session and does not call the server. + +* _@return {object}_ Returns the whole Batch Session object + +**Example** + +```javascript +var batchSession = jatos.batchSession.getAll(); +``` + + +### `jatos.batchSession.setAll` + +Replaces the whole session data. If the replacing object is rather large it might be better performance-wise to replace only individual paths. Each session writting involves sending the changes in the session via a JSON Patch to the JATOS server. If the session is large this data transfer can take some time. In this case use other session functions, like 'set', 'add', or 'replace'. + +* _@param {object} value_ - value to be stored in the session +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Set the whole Batch Session object + + ```javascript + var o = {"a": 123, "b": "foo"}; + jatos.batchSession.setAll(o); // Overwrites the current Batch Session with the object o + ``` + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + var o = {"a": 123, "b": "foo"}; + jatos.batchSession.setAll(o) + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSession.clear` + +Clears the whole Batch Session data and sets it to an empty object `{}`. + +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Clear the whole Batch Session + + ```javascript + jatos.batchSession.clear(); + ``` + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.batchSession.clear() + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSession.find` + +Gets a field in the Batch Session data. Takes a JSON Pointer and returns the matching value, or `undefined` if the pointer does not correspond to an existing field. Gets the object from the locally stored copy of the session and does not call the server. Contrary to `jatos.batchSession.get` it allows to get values from all levels of the Batch Session's object tree. + +* _@param {string} path_ - JSON pointer path +* _@return {object}_ - the value that is stored in path + +**Example** + +1. Find a field in the Batch Session + + If the Batch Session is `{"a": {"a1": "foo", "a2": "bar"}, "b": 999}` + + ```javascript + jatos.batchSession.find("/a/a1"); // returns "foo" + jatos.batchSession.find("/b"); // returns 999 + jatos.batchSession.find("/c/d"); // returns undefined + ``` + + +### `jatos.batchSession.defined` + +Checks in the Batch Session whether a field under the given path exists. Returns true if the field is defined and false otherwise. It's equivalent to `!jatos.batchSession.test(path, undefined)`. + +* _@param {string} path_ - JSON pointer path to be checked +* _@return {boolean}_ - 'true' if the field is defined and 'false' otherwise + +**Example** + +```javascript +jatos.batchSession.defined("/a"); // returns true if the pointer '/a' exists +``` + + +### `jatos.batchSession.test` + +JSON Patch test operation: Tests that the specified value is set in the document (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} path_ - JSON pointer path to be tested +* _@param {object} value_ - value to be tested +* _@return {boolean}_ + +**Examples** + +1. Test if a certain field in the Batch Session has a value + + If the Batch Session is `{"a": 123, "b": {"b1": "flowers", "b2": "animals"}}` + + ```javascript + jatos.batchSession.test("/a", 123); // returns true + jatos.batchSession.test("/a", 10); // returns false + jatos.batchSession.test("/b/b1", "flowers"); // returns true + ``` + +1. If you want to know the existence of a path in the Batch Session you can test against `undefined`. The function `jatos.batchSession.defined` provides a shortcut for this use case. + + ```javascript + if (!jatos.batchSession.test("/c", undefined)) { + // Path "/c" exists + } else { + // Path "/c" doesn't exist + } + ``` + + +### `jatos.batchSession.add` + +JSON Patch add operation: Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The `-` character can be used instead of an index to insert at the end of an array (see [jsonpatch.com](http://jsonpatch.com/)). If the path already exists in the Batch Session the value will be overwritten. The patch will fail if a key other than the last path element is missing, e.g., when the path is `"/a/b/c"`, if `"a"` and `"b"` do not already exist as keys, the patch will fail. + +* _@param {string} path_ - JSON pointer path +* _@param {object} value_ - value to be stored +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Add to an empty Batch Session + + ```javascript + jatos.batchSession.add("/a", 100); + ``` + + After the Batch Session is successfully updated the new object is `{"a": 100}`. + +1. Add to Batch Session + + If the Batch Session is `{"a": 100}` and one calls + + ```javascript + jatos.batchSession.add("/b", 123); + ``` + + then after the Batch Session is successfully updated the new object is `{"a": 100, "b": 123}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or fail + + ```javascript + jatos.batchSession.add("/b", 123) + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + +1. Add an object: + + ```javascript + jatos.batchSession.add("/obj", { foo: "bar" }) + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + Afterwards the Batch Session contains `{"obj": {"foo": "bar"}}`. + Note that `jatos.batchSession.add("/obj/foo", "bar")` will fail if `"/obj"` does not already point to an object. + +1. Add an array: + + ```javascript + jatos.batchSession.add("/array", [1, 2, 3]) + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + Afterwards the Batch Session contains `{"array": [1, 2, 3]}`. + +1. Add an element to an array: + + If the Batch Session is `{"array": [1, 2, 3]}` and one calls + + ```javascript + jatos.batchSession.add("/array/2", "new") + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + then afterwards the Batch Session contains `{"array": [1, 2, "new", 3]}`. + +1. Append to the end of an array using `/-`: + + If the Batch Session is `{"array": [1, 2, 3]}` and one calls + + ```javascript + jatos.batchSession.add("/array/-", "new") + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + then afterwards the Batch Session contains `{"array": [1, 2, 3, "new"]}`. + +1. Have a series of Batch Session updates + + ```javascript + jatos.batchSession.add("/a", 1) + .then(() => jatos.batchSession.add("/b", 2)) + .then(() => jatos.batchSession.add("/c", 3)) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSession.remove` + +JSON Patch remove operation: Removes a value from an object or array (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} path_ - JSON pointer path to the field that should be removed +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Remove from the Batch Session + + If the Batch Session is `{"a": 100, "b": 123}` and one calls + + ```javascript + jatos.batchSession.remove("/b"); + ``` + + then after the Batch Session is successfully updated the new object is `{"a": 100}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.batchSession.remove("/b") + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSession.replace` + +JSON Patch replace operation: Replaces a value. Equivalent to a 'remove' followed by an 'add' (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} path_ - JSON pointer path +* _@param {object} value_ - value to be replaced with +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Replace in the Batch Session + + If the Batch Session is `{"a": 100, "b": 123}` and one calls + + ```javascript + jatos.batchSession.replace("/b", 789); + ``` + + then after the Batch Session is successfully updated the new object is `{"a": 100, "b": 789}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.batchSession.replace("/b", 789) + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSession.copy` + +JSON Patch copy operation: Copies a value from one location to another within the JSON document. Both from and path are JSON Pointers (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} from_ - JSON pointer path to the origin +* _@param {string} path_ - JSON pointer path to the target +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Copy within the Batch Session from one location to another + + If the Batch Session is `{"a": "jatos"}` and one calls + + ```javascript + jatos.batchSession.copy("/a", "/b"); + ``` + + then after the Batch Session is successfully updated the new object is `{"a": "jatos", "b": "jatos"}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.batchSession.copy("/a", "/b") + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSession.move` + +JSON Patch move operation: Moves a value from one location to the other. Both from and path are JSON Pointers. (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} from_ - JSON pointer path to the origin +* _@param {string} path_ - JSON pointer path to the target +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Move within the Batch Session from one location to another + + If the Batch Session is `{"a": "jatos"}` and one calls + + ```javascript + jatos.batchSession.move("/a", "/b"); + ``` + + then after the Batch Session is successfully updated the new object is `{"b": "jatos"}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.batchSession.move("/a", "/b") + .then(() => console.log("Batch Session was successfully updated")) + .catch(() => console.log("Batch Session synchronization failed")); + ``` + + +### `jatos.batchSessionVersioning` + +This flag can be used to turn off versioning of the batch session. This speeds up updates to the batch session (patches) in certain cases where all concurrent patches are conflict-free between each other. If versioning is turned on (set to true) all session data patches are accompanied by a version. On the JATOS server side only a patch with the current version (as stored in the database) is applied. If there are multiple concurrent patches only the first one is applied. If versioning is turned off all patches arriving at the JATOS server are applied right away without checking the version. This is faster but can lead to unintended session data changes. By default versioning is turned on. + +**Example** + +```javascript +jatos.batchSessionVersioning = false; // Turns off versioning +``` + + +## Group variables + +The group variables are only filled with values if the current study run is a group study. + +### `jatos.groupMemberId` + +Group member ID is unique for this member (it is actually identical with the study result ID) + +### `jatos.groupResultId` + +ID of this group result (It's called group result to be consistent with the study result and the component result - although often it's just called group) + +### `jatos.groupMembers` + +List of member IDs of the current members of the group + +### `jatos.groupChannels` + +List of member IDs of the currently open group channels + + +## Group functions + +### `jatos.joinGroup` + +Tries to join a group and if it succeeds opens the group channel (which is mostly a WebSocket). Only if the group channel is open one can exchange data with other group members. As the only parameter this function takes an object that consists of several optional callback functions that will be called by _jatos.js_ when certain group events occur. It returns a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in joining. + +* _@param {object} callbacks_ - Defining callback functions for group events. All callbacks are optional. These callbacks functions are: + * `onOpen`: Is called when the group channel is successfully opened + * `onClose`: Is be called when the group channel is closed + * `onError`: Is called if an error during opening of the group channel's WebSocket occurs or if an error is received via the group channel (e.g. the Group Session data couldn't be updated). If this function is not defined _jatos.js_ will try to call the global `onJatosError` function. + * `onMessage(msg)`: Is called if a message from another group member is received. It gets the message as a parameter. + * `onMemberJoin(memberId)`: Is called when another member (not the worker running this study) joined the group. It gets the group member ID as a parameter. + * `onMemberOpen(memberId)`: Is called when another member (not the worker running this study) opened a group channel. It gets the group member ID as a parameter. + * `onMemberLeave(memberId)`: Is called when another member (not the worker running his study) left the group. It gets the group member ID as a parameter. + * `onMemberClose(memberId)`: Is called when another member (not the worker running this study) closed his group channel. It gets the group member ID as a parameter. + * `onGroupSession(path, op)`: Is called every time the Group Session changes on the JATOS server side. It gets two parameters: 1) JSON pointer path to the changed field in the Group Session as a parameter, and 2) JSON patch operation. + * `onUpdate()`: Combines several other callbacks. It's called if one of the following is called: `onMemberJoin`, `onMemberOpen`, `onMemberLeave`, `onMemberClose`, or `onGroupSession`. +* _@return {Promise}_ + +**Examples** + +1. Minimal example that joins a group and receives updates via the Group Session + + ```javascript + jatos.joinGroup({ + "onGroupSession": onGroupSession + }); + + function onGroupSession(path, op) { + var changedObj = jatos.groupSession.find(path); + console.log("Group Session was updated in path " + path + " with operation " + op + " to " + JSON.stringify(changedObj)); + } + ``` + +1. Example that defines the `onOpen`, `onMemberOpen`, and `onMessage` callbacks + + ```javascript + jatos.joinGroup({ + "onOpen": onOpen, + "onMemberOpen": onMemberOpen, + "onMessage": onMessage + }); + + function onOpen() { + console.log("You joined a group and opened a group channel"); + } + + function onMemberOpen(memberId) { + console.log("In our group another member (ID " + memberId + ") opened a group channel"); + } + + function onMessage(msg) { + console.log("You received a message: " + msg); + } + ``` + + +### `jatos.sendGroupMsg` + +Sends a message to all group members with an open group channel. Use `jatos.sendGroupMsgTo` to send a message to a particular member. + +Between group members data can be exchanged in fundamentally two different ways: sendGroupMsg/sendGroupMsgTo or the [Group Session](#functions-to-access-the-group-session). The main difference is that the Group Session is stored in JATOS database on the server side while with sendGroupMsg/sendGroupMsgTo the data are only relayed on the server side but is never stored. E.g. if the worker reloads the page all prior messages sent by sendGroupMsg/sendGroupMsgTo will be lost - on the other side, everything stored in the Group Session will be restored. But this storage of the Group Session in JATOS comes at the cost of being (slightly) slower. Which option to choose depends mostly on your study design. If you expect your workers to have an unreliable Internet connection or to reload the page then you should use the Group Session. If you just want to 'stream' current data to other members the use sendGroupMsg/sendGroupMsgTo. + +* _@param {object} msg_ - Any JavaScript object + +**Example** + + ```javascript + var msg = "Message for every group member"; // Send a text message + jatos.sendGroupMsg(msg) + + var objMsg = {"city": "Berlin", "population": 3500000}; // Send an object + jatos.sendGroupMsg(objMsg) + ``` + + +### `jatos.sendGroupMsgTo` + +Like `jatos.sendGroupMsg` but sends a message to a particular group member specified by the group member ID. You can find a list of all IDs of group members with an open channel `jatos.groupChannels`. Alternativally you get member IDs via the `onMemberOpen` callback function. + +* _@param {string} recipient_ - Recipient's group member ID +* _@param {object} msg_ - Any JavaScript object + +**Examples** + +1. Send a message to a group member with ID 1063 + + ```javascript + var msg = "Message for group member 1063"; + jatos.sendGroupMsgTo("1063", msg) + ``` + +1. Use the `onMemberOpen` callback to send a message right after a new member opened their group channel + + ```javascript + jatos.joinGroup({ + "onMemberOpen": onMemberOpen, + "onMessage": onMessage + }); + + function onMemberOpen(memberId) { + var msg = "Welcome to the group!"; + jatos.sendGroupMsgTo(memberId, msg); + } + + function onMessage(msg) { + console.log("You received a message: " + msg); + } + ``` + + +### `jatos.leaveGroup` + +Leaves the group it has previously joined. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the leaving. + +* _@param {optional function} onSuccess_ - Function to be called after the group is left +* _@param {optional function} onError_ - Function to be called in case of error +* _@return {Promise}_ + +**Example** + +```javascript +jatos.leaveGroup(); +``` + + +### `jatos.reassignGroup` + +Asks the JATOS server to reassign this study run to a different group. JATOS can only reassign if there is another group availible. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the reassigning. + +* _@param {optional function} onSuccess_ - Function to be called if the reassignment was successful +* _@param {optional function} onFail_ - Function to be called if the reassignment was unsuccessful +* _@return {Promise}_ + +**Example** + +```javascript +jatos.reassignGroup() + .then(() => console.log("Successful group reassignment: new group ID is " + jatos.groupResultId)) + .catch(() => console.log("Group reassignment failed")); +``` + + +### `jatos.setGroupFixed` + +Ask the JATOS server to fix this group. A fixed group is not allowed to take on more members although members are still allowed to leave. It offers callbacks, either as parameter or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), to signal success or failure in the fixing. + +* _@param {optional function} onSuccess_ - Function to be called if the fixing was successful +* _@param {optional function} onFail_ - Function to be called if the fixing was unsuccessful +* _@return {Promise}_ + +**Example** + +```javascript +jatos.setGroupFixed(); +``` + + +### `jatos.hasJoinedGroup` + +Returns true if this study run joined a group and false otherwise. It doesn't necessarily mean that we have an open group channel. We might just have joined a group in a prior component but in this component never opened the channel. If you want to check for an open group channel use `jatos.hasOpenGroupChannel`. + +**Example** + +```javascript +if(jatos.hasJoinedGroup()) { + // We are member in a group +} else { + // We are not member in a group +}; +``` + + +### `jatos.hasOpenGroupChannel` + +Returns true if we currently have an open group channel and false otherwise. Since you can't open a group channel without joining a group, it also means that we joined a group. On the other side although we have closed group channel we can still be a member in a group. Use `jatos.hasJoinedGroup` to check group membership. + +**Example** + +```javascript +if(jatos.hasOpenGroupChannel()) { + // We are member in a group and have an open group channel +} else { + // We do not have an open group channel (but could still be member in a group) +}; +``` + + +### `jatos.isMaxActiveMemberReached` + +Returns true if the group has reached the maximum amount of active members like specified in the batch properties. It's not necessary that each member has an open group channel. + +**Example** + +```javascript +if(jatos.isMaxActiveMemberReached()) { + // Maximum number of active members is reached +}; +``` + + +### `jatos.isMaxActiveMemberOpen` + +Returns true if the group has reached the maximum amount of active members like specified in the batch properties and each member has an open group channel. + +**Example** + +```javascript +if(jatos.isMaxActiveMemberOpen()) { + // Maximum number of active members is reached and each has an open channel +}; +``` + + +### `jatos.isGroupOpen` + +Returns true if all active members of the group have an open group channel and can send and receive data. It's not necessary that the group has reached its minimum or maximum active member size. + +**Example** + +```javascript +if(jatos.isGroupOpen()) { + // Each of the current members of the group have an open group channel +}; +``` + + +## Functions to access the Group Session + +The Group Session is one of three way to communicate between members of a group. The others are direct messaging (with [jatos.sendGroupMsgTo](#jatossendgroupmsgtorecipient-msg)) and broadcast messaging ([jatos.sendGroupMsg](#jatossendgroupmsgmsg)) (or: [more general information about the different session types](/Session-Data-Three-Types.html)). + +In difference to the [Batch Session](#functions-to-access-the-batch-session) the Group Session doesn't work from the start of a component. To use the Group Session you have to join a group ([with jatos.joinGroup](#jatosjoingroupcallbacks)). There you can also define a `onGroupSession` callback that gets called each time the Group Session changes regardless of the origin of the change. + +The Group Session is stored in JATOS' database on the server side. That means that all changes in the Group Session have to be synchronized between the client and the server. This is done via the group channel. Therefore all writing functions (`add`, `remove`, `clear`, `replace`, `copy`, `move`, `set`, `setAll`) can be paired with callback functions that will signal success or failure in the client-server sync. These callback functions can be either passed as parameters to `jatos.groupSession.[function_name]` or via a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +On the other side for all reading functions (`get`, `find`, `getAll`, `test`) there is no need to sync data between client and server, because _jatos.js_ keeps a copy of the Group Session locally. Therefore all reading functions do not offer callbacks, because there is no risk of failure of synchronization. + +Accessing the Group Session is done via [JSON Patches (RFC 6902)](https://tools.ietf.org/html/rfc6902) and +[JSON Pointer (RFC 6901)](https://tools.ietf.org/html/rfc6901). An introduction can be found under [jsonpatch.com](http://jsonpatch.com/). For JSON Patches _jatos.js_ uses the [JSON-Patch](https://github.com/Starcounter-Jack/JSON-Patch) library from Joachim Wester and for JSON Pointers the [jsonpointer.js](https://github.com/alexeykuzmin/jsonpointer.js) library from Alexey Kuzmin. + + +### `jatos.groupSession.get` + +Convenience function: like `jatos.groupSession.find` but works with a key instead of a JSON Pointer (without the slash in front of the key name). Therefore it works only on the first level of the session's object tree. It takes a name of an field within the Group Session and returns the matching value, or `undefined` if the key does not exist. For all other levels of the object tree use jatos.groupSession.find. Gets the object from the locally stored copy of the session and does not call the server. + +* _@param {string} name_ - name of the field +* _@return {object}_ - the value that is stored under name + +**Examples** + +1. Get a field from the Group Session + + Given the Group Session is `{"a": 1000, "b": "watermelon"}` + + ```javascript + // Since the parameter is the key's name and not a path it does not start with a "/" + var b = jatos.groupSession.get("b"); // b is "watermelon" + var c = jatos.groupSession.get("c"); // c is undefined + ``` + + the first line returns "watermelon" and the second undefined. + +1. With `jatos.groupSession.get` you can only access the first level of the object tree - if you want another level use `jatos.groupSession.find`. + + If the Group Session is `{"a": {"a1": 123, "a2": "watermelon"}}` + + ```javascript + var a1 = jatos.groupSession.get("a1"); // a1 is undefined !!! + var a = jatos.groupSession.get("a"); // a is { "a1": 123, "a2": "watermelon" } + ``` + + +### `jatos.groupSession.set` + +A convenience function for `jatos.groupSession.add`. Instead of a JSON Pointer path it accepts a name of the field to be stored (without the slash in front). Therefore it works only on the first level of the Group Session's object tree. If the name already exists in the Group Session the value will be overwritten. + +* _@param {string} name_ - name of the field +* _@param {object} value_ - value to be stored +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Set a field in the Group Session + + If the Group Session is `{"a": 1234}` + + ```javascript + // Since the parameter is the key's name and not a path it does not start with a "/" + var b = jatos.groupSession.set("b", "koala"); + ``` + + then after the Group Session is successfully updated the new object is `{"a": 1234, "b": "koala"}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.groupSession.set("b", "koala") + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + +1. Have a series of Group Session changes + + ```javascript + jatos.groupSession.set("a", 1) + .then(() => jatos.groupSession.set("b", 2)) + .then(() => jatos.groupSession.set("c", 3)) + .catch(() => console.log("Group Session synchronization failed")); + + +### `jatos.groupSession.getAll` + +Returns the complete Group Session data (might be bad performance-wise). Gets the object from the locally stored copy of the session and does not call the server. + +* _@return {object}_ Returns the whole Group Session object + +**Example** + +```javascript +var groupSession = jatos.groupSession.getAll(); +``` + + +### `jatos.groupSession.setAll` + +Replaces the whole session data. If the replacing object is rather large it might be better performance-wise to replace only individual paths. Each session writting involves sending the changes in the session via a JSON Patch to the JATOS server. If the session is large this data transfer can take some time. In this case use other session functions, like 'set', 'add', or 'replace'. + +* _@param {object} value_ - value to be stored in the session +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Set the whole Group Session at once + + ```javascript + var o = {"a": 123, "b": "foo"}; + jatos.groupSession.setAll(o); // Overwrites the current Group Session with the object o + ``` + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + var o = {"a": 123, "b": "foo"}; + jatos.groupSession.setAll(o) + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + +### `jatos.groupSession.clear` + +Clears the whole Group Session data and sets it to an empty object `{}`. + +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Clear the whole Group Session + + ```javascript + jatos.groupSession.clear(); + ``` + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.groupSession.clear() + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + +### `jatos.groupSession.find` + +Gets a field in the Group Session data. Takes a JSON Pointer and returns the matching value, or `undefined` if the pointer does not correspond to an existing field. Gets the object from the locally stored copy of the session and does not call the server. Contrary to `jatos.groupSession.get` it allows to get values from all levels of the Group Session's object tree. + +* _@param {string} path_ - JSON pointer path +* _@return {object}_ - the value that is stored in path + +**Example** + +Given the Group Session is `{"a": {"a1": "foo", "a2": "bar"}, "b": 999}` + +```javascript +jatos.groupSession.find("/a/a1"); // returns "foo" +jatos.groupSession.find("/b"); // returns 999 +jatos.groupSession.find("/c/d"); // returns undefined +``` + +the first line returns "foo" and the second 999. + + +### `jatos.groupSession.defined` + +Checks in the Group Session whether a field under the given path exists. Returns true if the field is defined and false otherwise. It's equivalent to `!jatos.groupSession.test(path, undefined)`. + +* _@param {string} path_ - JSON pointer path to be checked +* _@return {boolean}_ + +**Example** + +```javascript +jatos.groupSession.defined("/a"); // returns true if the pointer '/a' exists +``` + + +### `jatos.groupSession.test` + +JSON Patch test operation: Tests that the specified value is set in the document (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} path_ - JSON pointer path to be tested +* _@param {object} value_ - value to be tested +* _@return {boolean}_ + +**Examples** + +1. Test if a certain field in the Group Session has a value + + Given the Group Session is `{"a": 123, "b": {"b1": "flowers", "b2": "animals"}}` + + ```javascript + jatos.groupSession.test("/a", 123); // returns true + jatos.groupSession.test("/a", 10); // returns false + jatos.groupSession.test("/b/b1", "flowers"); // returns true + ``` + +the first line returns true, second false and third true. + +1. If you want to know the existence of a path in the Group Session you can test against `undefined`. The function `jatos.groupSession.defined` provides a shortcut for this use case. + + ```javascript + if (!jatos.groupSession.test("/c", undefined)) { + // Path "/c" exists + } else { + // Path "/c" doesn't exist + } + ``` + + +### `jatos.groupSession.add` + +JSON Patch add operation: Adds a value to an object or inserts it into an array. In the case of an array, the value is inserted before the given index. The `-` character can be used instead of an index to insert at the end of an array (see [jsonpatch.com](http://jsonpatch.com/)). If the path already exists in the Group Session the value will be overwritten. The patch will fail if a key other than the last path element is missing, e.g., when the path is `"/a/b/c"`, if `"a"` and `"b"` do not already exist as keys, the patch will fail. + +* _@param {string} path_ - JSON pointer path +* _@param {object} value_ - value to be stored +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Add an a field to the empty Group Session + + ```javascript + jatos.groupSession.add("/a", 100); + ``` + + After the Group Session is successfully updated the new object is `{"a": 100}`. + +1. Add an a field to the Group Session + + If the Group Session is `{"a": 100}` and one calls + + ```javascript + jatos.groupSession.add("/b", 123); + ``` + + then after the Group Session is successfully updated the new object is `{"a": 100, "b": 123}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.groupSession.add("/b", 123) + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + +1. Add an object: + + ```javascript + jatos.groupSession.add("/obj", { foo: "bar" }) + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + Afterwards the Group Session contains `{"obj": {"foo": "bar"}}`. + +1. Add to a nested object: + + If the Group Session is `{"a": {"b": {}}}` and one calls + + ```javascript + jatos.groupSession.add("/a/b/c", 123) + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + then afterwards the Group Session contains `{"a": {"b": {"c": 123}}}`. + + Note that `jatos.groupSession.add("/a/b/c", 123)` will fail if `"a"` and `"b"` do not exists and `"b"` is not an object. + +1. Add an array: + + ```javascript + jatos.groupSession.add("/array", [1, 2, 3]) + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + Afterwards the Group Session contains `{"array": [1, 2, 3]}`. + +1. Add an element to an array: + + If the Group Session is `{"array": [1, 2, 3]}` and one calls + + ```javascript + jatos.groupSession.add("/array/2", "new") + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + then afterwards the Group Session contains `{"array": [1, 2, "new", 3]}`. + +1. Append to the end of an array using `/-`: + + If the Group Session is `{"array": [1, 2, 3]}` and one calls + + ```javascript + jatos.groupSession.add("/array/-", "new") + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + then afterwards the Group Session contains `{"array": [1, 2, 3, "new"]}`. + +1. Have a series of Group Session updates + + ```javascript + jatos.groupSession.add("/a", 1) + .then(() => jatos.groupSession.add("/b", 2)) + .then(() => jatos.groupSession.add("/c", 3)) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + +### `jatos.groupSession.remove` + +JSON Patch remove operation: Removes a value from an object or array (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} path_ - JSON pointer path to the field that should be removed +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Remove a field from the Group Session + + If the Group Session is `{"a": 100, "b": 123}` and one calls + + ```javascript + jatos.groupSession.remove("/b"); + ``` + + then after the Group Session is successfully updated the new object is `{"a": 100}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.groupSession.remove("/b") + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + +### `jatos.groupSession.replace` + +JSON Patch replace operation: Replaces a value. Equivalent to a “remove” followed by an “add” (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} path_ - JSON pointer path +* _@param {object} value_ - value to be replaced with +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Replace a field in the Group Session + + If the Group Session is `{"a": 100, "b": 123}` and one calls + + ```javascript + jatos.groupSession.replace("/b", 789); + ``` + + then after the Group Session is successfully updated the new object is `{"a": 100, "b": 789}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.groupSession.replace("/b", 789) + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + +### `jatos.groupSession.copy` + +JSON Patch copy operation: Copies a value from one location to another within the JSON document. Both from and path are JSON Pointers (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} from_ - JSON pointer path to the origin +* _@param {string} path_ - JSON pointer path to the target +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Copy a field in the Group Session from one location to another + + If the Group Session is `{"a": "jatos"}` and one calls + + ```javascript + jatos.groupSession.copy("/a", "/b"); + ``` + + then after the Group Session is successfully updated the new object is `{"a": "jatos", "b": "jatos"}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.groupSession.copy("/a", "/b") + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + +### `jatos.groupSession.move` + +JSON Patch move operation: Moves a value from one location to the other. Both from and path are JSON Pointers. (see [jsonpatch.com](http://jsonpatch.com/)). + +* _@param {string} from_ - JSON pointer path to the origin +* _@param {string} path_ - JSON pointer path to the target +* _@param {optional callback} onSuccess_ - Function to be called if this patch was successfully applied on the server and the client side +* _@param {optional callback} onError_ - Function to be called if this patch failed +* _@return {Promise}_ + +**Examples** + +1. Move a field in the Group Session from one location to another + + If the Group Session is `{"a": "jatos"}` and one calls + + ```javascript + jatos.groupSession.move("/a", "/b"); + ``` + + then after the Group Session is successfully updated the new object is `{"b": "jatos"}`. + + Since there is a slight chance that the session update was not successful it's a good idea to provide callback functions for both cases. To provide success or fail callback functions you can either specify the onSuccess/onError parameters or use the returned [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise). + +1. Use returned Promise to handle success or failure + + ```javascript + jatos.groupSession.move("/a", "/b") + .then(() => console.log("Group Session was successfully updated")) + .catch(() => console.log("Group Session synchronization failed")); + ``` + + +### `jatos.groupSessionVersioning` + +This flag can be used to turn off versioning of the group session. This speeds up updates to the group session (patches) in certain cases where all concurrent patches are conflict-free between each other. If versioning is turned on (set to true) all session data patches are accompanied by a version. On the JATOS server side only a patch with the current version (as stored in the database) is applied. If there are multiple concurrent patches only the first one is applied. If versioning is turned off all patches arriving at the JATOS server are applied right away without checking the version. This is faster but can lead to unintended session data changes. By default versioning is turned on. + +**Example** + +```javascript +jatos.groupSessionVersioning = false; // Turns off versioning +``` diff --git a/versioned_docs/version-3.9.1/Run_your_study/Connect-to-Mechanical-Turk.md b/versioned_docs/version-3.9.1/Run_your_study/Connect-to-Mechanical-Turk.md new file mode 100644 index 0000000000..e8116bbb7e --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Connect-to-Mechanical-Turk.md @@ -0,0 +1,65 @@ +--- +title: Use MTurk +slug: /Connect-to-Mechanical-Turk.html +sidebar_position: 5 +--- + +Use your JATOS study with Mturk is easy, although a fair amount of clicking is required. + +A good idea is always to try it yourself first in [MTurk Sandbox](https://requester.mturk.com/developer/sandbox) before you let real workers do it. + +### You will need + +* A requester Mturk account +* Your study running on a [JATOS server](Bring-your-JATOS-online.html) +* A description of the study (this can be the same as the one you included in the study description within JATOS) + + +### On JATOS' side + +In JATOS, go to your study's page and click on the Study Links button and open the batch you want to run. + +![JATOS GUI screenshot](/img/v39x/study_links_mturk.png) + +1. Don't forget to enable the MTurk type + +1. Click on _Source Code_. You'll see a box with HTML code, similar to the one shown here. You will have to copy and paste the code from here to the MTurk interface. + +![JATOS GUI screenshot](/img/v39x/study_links_mturk_source_code.png) + + +### On MTurk's page + +You first have to create a project in the MTurk interface: + +1. Sign into your [MTurk requester account](https://requester.mturk.com/signin_options) (or [requester sandbox account](https://requestersandbox.mturk.com/signin_options)) + +1. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this [link for requester](https://requester.mturk.com/create/projects/new) (or this [link for requester sandbox](https://requestersandbox.mturk.com/create/projects/new)) + +1. Complete the *Enter Properties* tab + +1. Click on the *Design layout* button in the bottom of the page. + +1. Click on the *Source* button. You'll see some text in an editable window, corresponding to an HTML file. Delete the entire text in this field. + + ![MTurk Schreenshot](/img/MTurk-source-editor.png) + +1. Now paste the source code that you got from JATOS into this text field. This HTML code works out-of-the-box and you don't have to change anything (but you can if you want). + +1. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk. + + ![MTurk Schreenshot](/img/MTurk-source-editor-done.png) + + +### What should happen + +When an MTurk worker finishes a study they'll see a confirmation code like this one. + +![Confirmation code](/img/MTurk-confirmation-code_371.png) + +### How to check the confirmation codes + +To assign payment to individual workers, just compare the confirmation codes stored in JATOS' results page to those stored in MTurk. To see the confirmation codes in your results page you might have to add the column to your table: Like in the image, go to Customize and choose MTurk Confirmation Code. + +![Results of Mturk workers](/img/v39x/mturk-results.png) + diff --git a/versioned_docs/version-3.9.1/Run_your_study/Cross-sectional-and-longitudinal-studies.md b/versioned_docs/version-3.9.1/Run_your_study/Cross-sectional-and-longitudinal-studies.md new file mode 100644 index 0000000000..3d9b42550c --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Cross-sectional-and-longitudinal-studies.md @@ -0,0 +1,98 @@ +--- +title: Write cross-sectional and longitudinal studies +slug: /Cross-sectional-and-longitudinal-studies.html +sidebar_position: 7 +--- + +There are several situation in which you might want to store (some parts) of the result data in a way that is accessible from more than just a single study run. This might be the case if you want to: +1. counterbalance your conditions across participants to acount for order effects. +1. run a between-participants study. +1. run a longitudinal study. + +Whenever a participant clicks on a study link, JATOS internally starts a study run. Once the data from the last component are sumitted, the study run is finished and the data are no longer avalable to the client side. So, to run a cross-sectional or a longitudinal study, you need store data in a way that outlives the particular study run and is avalable to future runs. The [Batch Session data](Session-Data-Three-Types.html) does just this. + + +## 1. Counterbalance conditions between participants + +The basic idea here is simple. Every time a new participant clicks on a study link, you assign them randomly to one of the possible conditions. And you keep track of how many participants did each condition in the Batch Session data. + +Have a look at the ["Randomize tasks between workers"](/Example-Studies) study in our examples for a full example that you can easily add as a first component in your study. + +## 2. Run cross-sectional designs + +From the coding perspective, the exact same logic applies as for point 1. But please remember: different participants may run a study using different computers with different processing speed, operating systems and browser. All these factors can influence the timing of your response. So be careful when comparing different populations (epecially if they differ in demographics) as they might present systematic differences in the computers they run your study from. See [this paper](https://link.springer.com/article/10.3758/s13428-015-0567-2) for a more thorough discussion. + + +## 3. Write longitudinal studies + +You might want to collect data from the same participant multiple times and, crucially, be able to link the multiple result data from a single participant. The first thing you need to do is make sure that the same *person* is assigned a single, unique ID. There are several options for this, and your exact solution may depend on how you are recruiting participants. + +### Using Personal Multiple study links + +If your sample size is relatively small and it is logistically doable, you could send individualized [Personal Multiple study links](Run-your-Study-with-Study-Links.html) to each participant. If a participant runs a study with this study link, JATOS will assign them a unique number. You can access the worker ID in your JavaScript through [`jatos.workerId`](jatos.js-Reference.html#jatosworkerid) from the _jatos.js_ library. + +### Using MTurk + +If you are recruiting participants through a MTurk, it's straightforward: You can access MTurk's worker ID in your JavaScript through `jatos.urlQueryParameters.workerId`. Alternatively you can also use JATOS' [`jatos.workerId`](jatos.js-Reference.html#jatosworkerid). + +### Using Prolific + +If you are usning Prolific to recruit participants, it's a bit more complicated. To access the worker ID, you first need to tell Prolific to include it in their query parameters. In Prolific, go to Study Settings and enable the option to include special query parameters in the URL. + +![Prolific Screenshot](/img/Screenshot_ExtendURL_Prolific.png) + +If you select these options in Prolific, you'll be able to collect the Prolific ID from your JavaScript by using `jatos.urlQueryParameters`, e.g. + +```javascript +var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID; +``` + +### Using a General Multiple link with IDs assigned to individual workers + +If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a [General Multiple link](Worker-Types.html#-general-multiple-worker), you could provide each new participant with a unique ID that they then have to store and provide (manually) in the following session. Note that, when a participant runs a study with a General Single JATOS stores cookies on their browser to prevent them from taking part twice in the same study. But these cookies are minimal and not intended to be used to identify participants or to link a browser to any given result data. + + +## Store bits of result data that are necessary for future sessions + +Once you have an ID, you should assign to it the information relevant for the following sessions in your longitudinal study. Say you need to store the number of correct responses for a given session. You could do it with the command: + +```javascript +var performanceInfo = {"percentageCorrect" : nCorrect/nTrials, "nTrials" : nTrials} +jatos.batchSession.add("/subjects/" + ID, performanceInfo); +``` + +Which will append the information from `ID` and `percentageCorrect` to the already existing Batch session data and give you something that looks (e.g.) like this in the Batch session: + +```javascript +{ + "subjects": { + "MyemLF": { + "percentCorrect": 62, + "nTrials" : 250 + }, + "74b61m": { + "percentCorrect": 78, + "nTrials" : 250 + }, + "pFyxRT": { + "percentCorrect": 67, + "nTrials" : 247 + } +} +``` + + +**Note that the information stored in the Batch Session is visible to the client side, so it should contain only the strictly necessary, pseudonymized data.** In other words, store only summary data like the condition assigned, number of trials completed or correct, etc. But nothing else. + + +## Recover the corresponding bit of the result data from the Batch Session + +You could do that with the following command: + +```javascript +var subjsPreviousPerformance = jatos.batchSession.getAll().subjects[ID] +``` + +That's it. Once you have your worker's ID and the corresponding longitudinally-relevant data, you can use it as a starting point for your next session. + + diff --git a/versioned_docs/version-3.9.1/Run_your_study/Deploy-to-a-server-installation.md b/versioned_docs/version-3.9.1/Run_your_study/Deploy-to-a-server-installation.md new file mode 100644 index 0000000000..57bf55832c --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Deploy-to-a-server-installation.md @@ -0,0 +1,23 @@ +--- +title: Deploy to a server installation +slug: /Deploy-to-a-server-installation.html +sidebar_position: 1 +--- + +Usually you conveniently develop your study on your local computer where you have a [local installation of JATOS](Installation.html). Then just use the export and import buttons in your installations to transfer the study to your [JATOS server](Bring-your-JATOS-online.html). + +If you have a server already, you will need to take your ready-to-run study from your local installation and deploy it to the server. In order to do this: + +1. On your *local* JATOS installation, open your study and click on **Export** in the study toolbar. A pop-up window will appear. Save the [_.jzip_](JATOS-Study-Archive-JZIP.html) file wherever you like on your computer. +1. On your *server* JATOS, go to the study sidebar (click top-left on **Studies**), click "**+**", and then **Import study**. Select the _.jzip_ file you have exported earlier. + + +**Please note that:** + +* The two JATOS look almost identical, and you will (basically) only distinguish them on the basis of the URL in the browser. To prevent confusion, we've made it easier: A local JATOS installation has a **gray** JATOS logo in the top bar - a server installation a **colored** logo. +* A **_.jzip_** file is a [JATOS Study Archive](JATOS-Study-Archive-JZIP.html). It is using the ZIP archive file format. It contains everything to describe a study like study properties and study assets. Do not unzip it - Always import the *.jzip* to JATOS. +* In the process of exporting/importing you'll transfer all assets of your study (HTML/JS/CSS files, images, audio, etc) contained in the local study folder. You will **not** transfer result data. +* If you want to make changes to a study, we also recommend that you do so in the local JATOS. There you have full access to the study assets and can change and edit them easily. Then again you can Export → Import to the JATOS server. + + + diff --git a/versioned_docs/version-3.9.1/Run_your_study/End-page-after-your-study-finished.md b/versioned_docs/version-3.9.1/Run_your_study/End-page-after-your-study-finished.md new file mode 100644 index 0000000000..be425551ed --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/End-page-after-your-study-finished.md @@ -0,0 +1,54 @@ +--- +title: End page - After your study finished +slug: /End-page-after-your-study-finished.html +sidebar_position: 9 +--- + +By default JATOS just shows the text "**This study is finished. Thank you for your participation.**" in English language, with no special formatting, after a study finished. Maybe you want a different language or add a logo and different text or styling, then read on. + + +### 1. endPage.html + +If you include a file named '_endPage.html_' in your study assets folder along with your other study's files, JATOS will automatically redirect to this page after the study finished. + +**Hint 1:** Be aware that in the '_endPage.html_' you cannot load or use any other files from the study assets folder. Because the study is already finished, JATOS won't allow you to access any other file from this folder, or from any of the JATOS sessions (study, batch and group) out of security reasons. Of course this doesn't prevent you from loading images or libraries (or any other resource) directly from the internet. + +**Hint 2:** If you run the study with an **MTurk Worker** then you probably want to show the confirmation code to your worker. This is passed on to the _endPage.html_ in a cookie with the name *JATOS_CONFIRMATION_CODE*. + +**Hint 3:** If you run your study with the **JATOS GUI (Run button)** it won't show you the _endPage.html_ but redirect you back to JATOS' GUI instead. + + +### 2. Study Properties' End Redirect URL + +Maybe you want to redirect to a different page, e.g. a Prolific's end page or your department's webpage. This you can do by putting the URL of that page into the study properties in JATOS' GUI. + +![screenshot](/img/v39x/end-redirect-url.png) + +**Hint:** If you run the study with an **MTurk Worker** then you probably want to show the confirmation code to your worker. This is passed on as an URL query parameter *confirmationCode*. + +You can pass on arguments from the original study link URL to redirect URL. Squared brackets in the _End Redirect URL_ indicate that the string between those brackets is a parameter from the original study run link URL and let JATOS replace the the whole _[string]_ by the value of the parameter. + +E.g. + +* If your study link is: + + ``` + http://myjatosdomain/publix/v6UkpHR8Sfu?SONA_ID=123abc + ``` + +* And your _End Redirect URL_ (in study properties): + + ``` + https://rug.sona-systems.com/webstudy_credit.aspx?experiment_id=123&credit_token=1234567&survey_code=[SONA_ID] + ``` + +* Then JATOS will after a study finished automatically replace [SONA_ID] with _123abc_ and redirect to: + + ``` + https://rug.sona-systems.com/webstudy_credit.aspx?experiment_id=123&credit_token=1234567&survey_code=123abc + ``` + + +### 3. In JavaScript with `jatos.endStudyAndRedirect` or `jatos.endStudyAjax` + +If you want to determine dynamically (i.e. in JavaScript) the address of the webpage that your participants see after finishing a study, you can use one of the two _jatos.js_ functions [`jatos.endStudyAndRedirect`](jatos.js-Reference.html#jatosendstudyandredirect) or [`jatos.endStudyAjax`](jatos.js-Reference.html#jatosendstudyajax) in the JavaScript of your study's **last component**. This is the most versatile way. diff --git a/versioned_docs/version-3.9.1/Run_your_study/Manage-Results.md b/versioned_docs/version-3.9.1/Run_your_study/Manage-Results.md new file mode 100644 index 0000000000..072a7fe2b0 --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Manage-Results.md @@ -0,0 +1,133 @@ +--- +title: Manage Results +slug: /Manage-Results.html +sidebar_position: 8 +--- + +## Results Pages + +Once you collected data for a study, you can see and manage the results by clicking on one of the *Results* buttons. + +![Results Link](/img/v39x/results_link.png) + +The image below is an example of a study results page, but there are result pages for components, batches or groups as well. There's quite a lot of information here, so we'll go through each piece. + +![Results View screenshot](/img/v39x/results_view_12.png) + + +## Interacting With The Results Table + +### View Result Data + +Each study result has an arrow on the left. If you click on it, the result data for this study run will be displayed underneath the row. Since a study can have several components and each component produces its own result data there can be several result data each in its own row (like in the screenshot below). By clicking on _show all_ one can see the whole data if it doesn't fit all in the box. + +![Results View screenshot](/img/v39x/results_view_11.png) + + +### Selecting Results + +There is a checkbox on the left side of each row to select/deselect a specific result. You can also use the buttons on the bar above to select/deselect all results in the table. Additionally you can select only the filtered ones or only the visible ones. + +![Results View screenshot](/img/v39x/results_view_13.png) + + +### Filter Results & Filter Builder + +The filter lets you search all all fields in the results table (the metadata). + +![Results View screenshot](/img/v39x/results_view_14.png) + +If you type, for example, "Personal Single" in the *Filter* field, only the results ran by a Personal Single worker will appear on the table. You can then click on *Filtered* to select them and export only those results that you're interested in. + +For more eloborate filtering you can use Regular Expressions. Click on *RegEx* to activate this. + +By default filtering in case insensitive but you can turn on case sensitive filtering by clicking on *Aa*. + +Sometimes the simple filter is not precise enough or you want to combine multiple filters: For those cases the _Filter Builder_ offers complex criteria with logical conjunctions ('and', 'or'). It's also possible to filter for certain dates. + +![Results View screenshot](/img/v39x/results_view_15.png) + + +## Export Results + +![Results View screenshot](/img/v39x/results_view_16.png) + +Once you selected the results you're interested in, click *Export Results*. You can choose what you want to export: everything in a JATOS Results Archive, only the result metadata, only the result data, or only the files. If in doubt which one to choose, get the JATOS Result Archive - it contains everything. + + +### Export a JATOS Results Archive (JRZIP) + +![Results View screenshot](/img/v39x/results_view_17.png) + +Since version 3.8.1 this is the standard export format. It **aggregates result data, result files and result metadata** in one ZIP archive file with a _.jrzip_ file extension ([more information about JRZIP](JATOS-Results-Archive-JRZIP.html)). + + +### Export Result Data + +![Results View screenshot](/img/v39x/results_view_18.png) + +The result data are the genuine data that got submitted during study runs without any metadata or result files. You can choose between ***ZIP*** or ***Plain Text*** format. In the _ZIP_ format the result data are stored in a file system structure with folders for study results and component results, similar to the _JRZIP_ format. The _Plain Text_ format is familiar from previous JATOS version: all result data are put together in one text file with one result per line. + + +### Export Result Files + +![Results View screenshot](/img/v39x/results_view_19.png) + +The result files are the files that were uploaded during study runs. They are exported as an ZIP archive with a file system structure that represents the study results and their component results. + + +### Export Result Metadata + +![Results View screenshot](/img/v39x/results_view_20.png) + +The metadata are mostly the data that you see in the result table but that do not belong to the actual result data or files, e.g. worker ID or start time. You can choose between ***JSON*** and ***CSV*** format. + + +## Delete Results + +![Results View screenshot](/img/v39x/results_view_21.png) + +You can click *Delete* to remove the selected results. That includes result data, result files and metadata. Keep in mind **there's no undo function for this**. + + +## Table Columns and Customization + +You can show and hide the columns displayed in the table with the drop-down menu under the *Customize* button. + +![Results View screenshot](/img/v39x/results_view_22.png) + +* **Result ID** - An identifier assigned by JATOS to each study result. A study result is actually a set of component results, each of them with their own (different) *Component Result ID*. +* **UUID** - universally unique identifier - similar to Result ID but this ID is unique over different JATOS installations +* **Study Code** - The study code that was used to start this study run +* **Start Time** - Time at which the first component of the study was started. +* **End Time** - Time at which the last component of the study was finished. +* **Last Seen** - Each component running in a worker's browser sends a "heartbeat" regularly back to JATOS. Last Seen is the time of the last heartbeat received. The heartbeat stops either when the study is finished or when the browser tab is closed. The default period of the heartbeat is 2 minutes but you can change it through a [_jatos.js_ function](jatos.js-Reference.html#jatossetheartbeatperiod). +* **Duration** - Simply the time difference between the start and end time. +* **Batch** - Name of the batch the worker belongs to. +* **Worker ID** - Assigned by JATOS. Each worker has its own Worker ID. JATOS' admin user will always have Worker ID 1. You can click on a Worker ID to see all the worker's results. +* **Worker Type** - Displays the [Worker type](Worker-Types.html) that ran the study. +* **MTurk Worker ID** - Only applies to studies run by MTurk workers. An identifier given by Amazon Mechanical Turk's, not by JATOS. +* **MTurk Confirmation Code** - Only applies to studies run by MTurk workers. The Confirmation Code is generated by JATOS and given to the worker as proof of his work. +* **Group ID** - Only available for group studies. It identifies the group. +* **Files** - Indicates result file upload +* **Data Size** - (Component Results only) - Size of the result data as it is stored in the database +* **Files (Size)** - (Component Results only) - List of the uploaded result files with their size in brackets +* **State** + + Possible states for _study results_ are: + * PRE - [Preview of study](Restricting-study-flow.html#preview-links) (exists only in PersonalSingleWorker and GeneralSingleWorker) + * STARTED - Study started + * DATA_RETRIEVED - The very beginning of the study. It means the first component of the study was loaded in the worker's browser and started running. (It literally means the browser asked for the initialization data.) + * FINISHED - Study finished. All result data and files that were sent by the study in the browser were safely stored in JATOS. + * ABORTED - Study aborted by worker and all result data and files were deleted. + * FAIL - Something went wrong, study stopped and cannot continue + + Possible states for _component results_ are: + * STARTED - Component started + * DATA_RETRIEVED - The very beginning of the component. It means the component was loaded in the worker's browser and started running. (It literally means the browser asked for the initialization data.) + * FINISHED - Component finished. All result data and files that were sent by the study in the browser were safely stored in JATOS. + * RELOADED - Component was reloaded (usually by clicking the browser's reload button) + * ABORTED - This component's study was aborted by worker and all result data and files were deleted. + * FAIL - Something went wrong, the study stopped and cannot continue + +* **Messages** - A message that can be set together with [`jatos.endStudy`](jatos.js-Reference.html#jatosendstudy) or [`jatos.abortStudy`](jatos.js-Reference.html#jatosabortstudy). diff --git a/versioned_docs/version-3.9.1/Run_your_study/Restricting-study-flow.md b/versioned_docs/version-3.9.1/Run_your_study/Restricting-study-flow.md new file mode 100644 index 0000000000..544d80ac9d --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Restricting-study-flow.md @@ -0,0 +1,63 @@ +--- +title: Restricting study flow - reloading, linear studies, single-use workers and previews +slug: /Restricting-study-flow.html +sidebar_position: 4 +--- + +## Intro: Restricting study flow + +Let's first say what we understand under the _study flow_: + +**Study flow** - the intended order of a study's components as they are done by the participants running the study. This doesn't necessarily has to be the order of components like they are defined in the study page, meaning going forward one-by-one - instead the study flow can go backwards to a previous component, go in a loop over several components, or reload the current component. It is even possible to decide on-the-fly in your JavaScripts what the next component will be. In general and by default a component can go to any other component including itself. The _jatos.js_ functions to determine the study flow are `jatos.startNextComponent`, `jatos.startComponentByPos`, `jatos.startLastComponent` and `jatos.startComponent`. + +**Common restrictions** +- You want to prevent a participant from reloading the same component (by using the browser's reload button). +- You want to ensure a linear study flow and prevent participants from going backwards (by using the browser's back button). +- You want to prevent a participant from running a study twice. +- You want to allow participants to first have a peek into a study and preview it without actually starting the study and fully committing to it. + +... and how to do it: + + +## Allow reload or prevent a reload of the same component + +A worker can press their browser's reload button and by default JATOS will respond with the same component again: by default, the worker can do a component multiple times. To prevent this each **component properties** has a checkbox _Allow reload_. + +![GUI Screenshot](/img/v39x/component-properties-reload.png) + +If you want to prevent this behaviour uncheck the box. If a participant reloads the page, they will see an error message. Then the study run will be finished and put to state FAIL. Since each component properties has their own _Allow reload_ checkbox it can be defined differently for each component, e.g. reloading is allowed in the introduction but is prohibited in the actual experiment. + +**Hint**: You should tell your workers in your study description if you disable reloads, in order to prevent them from accidentally pressing the reload button and failing your study. Consider also adding a warning (e.g. a pop-up) informing participants that they will not be able to continue with the study. + +**Another hint**: The (unchecked) _Allow reload_ and the (checked) _Linear study flow_ properties can be combined to achieve a strictly increasing study flow. + + +## Ensure a linear study flow + +A worker can press their browsers back button and by default JATOS will response with the previous component, the one that was done before by the worker. This might allow a worker to divert from the intended study flow. To prevent this each **study properties** has a checkbox _Linear study flow_. + +![Study Properties Screenshot](/img/v39x/study-properties-linear-flow.png) + +If you want to enforce a linear study flow check the box. Then, if a participant tries to go backwards in their browser, they will see an error message instead. The study run will be finished and put to state FAIL. + +**Hint**: You should tell your participants in your study's description if you enforce a linear study flow to prevent them from accidentally pressing the back button and failing your study. Consider also adding a warning (e.g. a pop-up) informing participants that they will not be able to continue with the study. + +**Another hint**: If you want to loop over components, un-check this box. + +**Yet another hint**: The (unchecked) _Allow reload_ and the (checked) _Linear study flow_ properties can be combined to achieve a strictly increasing study flow. + + +## Single-use study links - prevent workers running the study twice + +Often you want to prevent a participant from running the same study twice. To achieve this use the _single-use_ study link types: _Personal Single_ and _General Single_. + +Read more on the [different worker types available in JATOS](Worker-Types.html) and [about study links](Run-your-Study-with-Study-Links.html). + + +## Allow preview + +Sometimes, when you hand out study links, your participants mindlessly click on the link right away and are not aware that they have already started the study. If they do not intend to run the study right away this is a problem with _single-use_ study links (**General Single** or **Personal Single**). + +![GUI Screenshot](/img/v39x/study-properties-allow-preview.png) + +With allowing previews in the **study properties** you can let your workers peek into a study without devaluing the study link. They can run the **first component** of your study as often as they wish and the study link gets devalued only after starting the second component. This only makes sense if you don't put your actual experiment in the first component, but some kind of description and/or consent form. Then your workers can click the study link, see the description and decide to do the study later. diff --git a/versioned_docs/version-3.9.1/Run_your_study/Run-your-Study-with-Study-Links.md b/versioned_docs/version-3.9.1/Run_your_study/Run-your-Study-with-Study-Links.md new file mode 100644 index 0000000000..d6231c342f --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Run-your-Study-with-Study-Links.md @@ -0,0 +1,158 @@ +--- +title: Run your Study with Study Links +slug: /Run-your-Study-with-Study-Links.html +sidebar_position: 2 +--- + +Study Links in JATOS is the name of a page where one can generate study links for your participants (also called workers in JATOS) to run your study. You can also organize your participants into batches and handle their results there. + +To get to the Study Links page press on the button **Study Links** in your study's page: + +![Study Links Button screenshot](/img/v39x/study_links_1.png) + +In the beginning every study has only one batch, the 'Default' one, but more can be added. A batch can have study links of different type, e.g. Personal Single, Personal Multiple etc: + +![Study Links page screenshot](/img/v39x/study_links_2.png) + + +## Study links - How to let participants run your study + +During development of your study you would usually run it with the "Run" button in the study page. But then, when you are done developing you want to let others run your study - you want participants (or workers as they are called in JATOS) do it. For this JATOS lets you create study links that you can hand out to your workers (e.g. via email or social media). + +**Generate study links and hand them to your workers** + +JATOS has different study link types and each type corresponds to a worker type with different properties, that are well explained on a dedicated page: [Worker Types](Worker-Types.html). + +![Study Links page screenshot](/img/v39x/study_links_3.png) + +Click on the "**▼**" button in the left of the batch row (red box) to expand the study link types (if it's not already expanded). + +![Study Links page screenshot](/img/v39x/study_links_7.png) + +You can de-/activate a study link type by clicking on the switch in the left of each row (red box). Deactivated types cannot be used to run a study. Always check before you send out study links that the corresponding types are activated. + + +### Personal type links: Personal Single or Personal Multiple + +![Study Links page screenshot](/img/v39x/study_links_4.png) + +Personal type links can be either "Single" or "Multiple". You can find more details about them in the [Worker Types](Worker-Types.html) page, but the gist is that the links are meant to be handed to individual workers (hence _Personal_). Personal Single links can be used once, whereas Personal Multiple can be used many times. + +After clicking the **Study Links** button you get a new window where you can create and manage the study links of this type. + +![Study Links page screenshot](/img/v39x/study_links_11.png) + +1. This button creates one study link without a comment. This button is a shortcut to the "New Study Links" button. +1. Lets you create several study links and lets you add a comment to them. The comment is only a hint for you that you can use to distinguish your study links. You can create Personal type study links in bulk by changing the Amount value. +1. This is the study code. [You can hand this to your workers](Run-your-Study-with-Study-Links.html#study-code--study-entry-page). +1. This is your actual study link. Hand this to your workers. There are two links that can be toggled by a button: 1) [The 'Open Directly' link starts the study right away](Run-your-Study-with-Study-Links.html#start-directly-with-a-study-link). 2) [The 'Confirm First' lets your worker confirm first with a button press](Run-your-Study-with-Study-Links.html#study-link--study-entry-page-for-confirmation). Use the button to copy the link to the clipboard or to get the QR code. +1. Use this checkbox to de-/activate a single study link. A deactivated study link can not be used to start a study run (but an already started study run can continue to run). +1. Use these buttons to filter the study links. You can show _All_, only the _Active_ or _Deactivated_ ones, or show only the links that were already _Used_. + +![Study Links page screenshot](/img/v39x/study_links_14.png) + +Use QR codes to make your study easier accessible with mobile phones. E.g. copy+paste the QR code image into an email or print it out and post it on a bulletin board. + + +### General type links: General Single or General Multiple + +![Study Links page screenshot](/img/v39x/study_links_5.png) + +General type links can be either Single or Multiple. You can find more details about them in the [Worker Types](Worker-Types.html) page, but the gist is that all workers (or at least many) get the same link (hence _General_). The General Single link can be used once whereas General Multiple can be used many times. + +Due to the nature of these types there is only one study link per type. Click on the button Study Link to get it. + +![Study Links page screenshot](/img/v39x/study_links_15.png) + +There are two links that can be toggled by a button: 1) [The 'Open Directly' link starts the study right away](Run-your-Study-with-Study-Links.html#start-directly-with-a-study-link). 2) [The 'Confirm First' lets your worker confirm first with a button press](Run-your-Study-with-Study-Links.html#study-link--study-entry-page-for-confirmation). Use the button to copy the link to the clipboard or to get the QR code. Use QR code to make your study easier accessible with mobile phones. E.g. copy+paste the QR code image into an email or print it out and post it on a bulletin board. + + +### MTurk type links + +![Study Links page screenshot](/img/v39x/study_links_6.png) + +How to connect to MTurk and create study links is described in its own page: [Connect to Mechanical Turk](Connect-to-Mechanical-Turk.html). + + +## Study Entry Page + +A study run can be started in JATOS in slightly different ways: + +1. [Start directly with a study link](Run-your-Study-with-Study-Links.html#start-directly-with-a-study-link) +1. [Study link + Study Entry page for confirmation](Run-your-Study-with-Study-Links.html#study-link--study-entry-page-for-confirmation) +1. [Study code + Study Entry page](Run-your-Study-with-Study-Links.html#study-code--study-entry-page) + +**QR codes** can be used instead of study links but they are essentially just another representation of the links (using little black and white rectangles instead of characters). + +### Start directly with a study link + +If you toggle the Study Link(s) button to 'Open Directly' the generated link will start the study run directly without any intermediate steps like the Study Entry page. The study link has the format `https://my.jatos.server/publix/study-code`, e.g. `https://cortex.jatos.org/publix/GwtCkuCY4bM`. This is fast for the participant but has the disadvantage that if they click the study link accidentally, at least if it is a single-use link (Personal Single or General Single), it will be invalidated and the participant is not allowed to run the study again (not without handing them a new study link). + + +### Study link + Study Entry page for confirmation + +If you toggle the Study Link(s) button to 'Confirm First' the generated link will first show the Study Entry page and only when clicked the '' button start the actual study run. + +This is how the Study Entry page might look like (you can customize the message): + +![Study Entry page screenshot](/img/study_entry_page_1.png) + +The study link has the format `https://my.jatos.server/publix/run?code=study-code`, e.g. `https://cortex.jatos.org/publix/run?code=GwtCkuCY4bM`. As you can see it uses the URL query parameter 'code' to pass on the study code. + +The advantage of using the Study Entry page is, that participants accidentally clicking on a study link (e.g. in in an email or on Twitter) without the intention of actually running the study (just out of curiosity) will now **not** automatically start the study run but be shown the Study Entry page where they have to press the '' button for confirmation. At least single-use links (Personal Single or General Single) can be used only once. Here the study entry page acts as a kind of barrier preventing the invalidation of the link. + +#### Customization of the message + +By default the message on the Study Entry page is something like 'Press to start the experiment'. You might want to change the language or add some more introductory text. You can do this in the study's Study Properties + + +### Study code + Study Entry page + +You can also just hand out the Study Code and let your participants enter it themselves in the Study Entry page. The URL to the Study Run page is `https://my.jatos.server/publix/run`. + +It will show a field where the study code can be entered. And after pressing the '' button the study starts: + +![Study Entry page screenshot](/img/study_entry_page_3.png) + +The advantage of using the Study Entry page with the study codes is similar to a [Study link + Study Entry page for confirmation](Run-your-Study-with-Study-Links.html#study-link--study-entry-page-for-confirmation): the participant cannot accidentally start a study run. Additionally a study code is easier to deliver orally than a study link, e.g. per phone (it's just 11 digits). + + +## Batches - How to organize your study links and workers + +A batch is a collection of study links and their assoziated workers. Using different batches is useful to organize your study runs, separate their results and vary their setup. E.g. you could separate a pilot run from the "proper" experiment, or you could use different batches for different worker types. + +Batches are organized in the Study Links page. Here you can create and delete batches, access each batch's properties and edit its **Batch Session Data** or look through their results. + +Each study comes with a "Default" batch (although it can be renamed in its batch properties). + +![Study Links page screenshot](/img/v39x/study_links_12.png) + +You can **deactivate** or **activate** a batch by clicking on the checkbox button in each batch row. A deactivated batch doesn't allow any study runs. + + +### Batch Properties + +Each batch has properties that can be changed: click on the Batch Properties button in each batch's row. + +![Study Links page screenshot](/img/v39x/study_links_13.png) + +* For each batch, you can limit the maximum number of workers that will ever be able to run a study in this batch by setting the **Maximum total workers**. + +* Additionally you can switch on or off study link types in the **Allowed types**. Unchecked types are not allowed to run a study. This has the same effect as de-/activating the type in the batch. Always check before you send out study links that the corresponding types are activated. + +* A batch can have some **batch input** [similar to the one in the study or component properties](Write-your-own-Study-Basics-and-Beyond.html#study-json-input-and-component-json-input). The difference is that this one is only accessible from every study run in this batch. + +* The **Group Properties** relate to [group studies](Write-Group-Studies-I-Setup.html#group-settings-in-each-batchs-properties). + + +### Groups + +A batch is also the place where [JATOS groups](Write-Group-Studies-I-Setup.html) are handled. Here you can an get an overview of the Groups that belong to this batch: see what their member workers are or edit the **Group Session Data**. + +![Groups table](/img/v39x/groups_view.png) + +* **Fixed** this button allows you to _fix_ a group. A fixed group doesn't allow new members to join. It keeps the group as it currently is. It has the same effect as the _jatos.js_' function [`jatos.setGroupFixed`](jatos.js-Reference.html#jatossetgroupfixed) ([more info](Write-Group-Studies-II-JavaScript-and-Messaging.html#fixing-a-group)). +* **Active Workers** are the workers that are currently members in the group +* **Past Workers** the ones that were members at one point in the past +* **Results** shows only the study results that belong to this group +* **Group State** can be START, FINISHED, or FIXED diff --git a/versioned_docs/version-3.9.1/Run_your_study/Study-Log.md b/versioned_docs/version-3.9.1/Run_your_study/Study-Log.md new file mode 100644 index 0000000000..0a0361f666 --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Study-Log.md @@ -0,0 +1,23 @@ +--- +title: Study Log +slug: /Study-Log.html +sidebar_position: 10 +--- + +JATOS stores a log file for each study (not to be confused with [JATOS' log](Troubleshooting.html#read-log-file-in-the-browser) which is for the whole application). This file has a line for every relevant event that happened in a study, most importantly when a component result was saved, exported or deleted. Also, it contains a hash - a string that is generated by the contents of the result data itself. This, in principle, would allow any JATOS user to show that the data have not been modified, and that no result was deleted between data collection and publication. + +You can see the log by clicking on **More** in the study toolbar and then **Study Log**: + +![Study Log button](/img/v39x/study_log_button.png) + +Then the log looks similar to this: + +![Study Log pretty](/img/v39x/study_log_pretty.png) + +**A few more details:** +* The study log won't be necessary in most cases. Just nice to have. Just in case. +* In the GUI you will see only the **last 100 entries** of the study log but you can get the whole log by downloading it. In the GUI the log is in **reversed** order - the downloaded one has normal order. +* The following events are logged: **create/delete study**, **run/finish study**, **store result data**, **upload result file**, **export result data** +* In case of storing result data or uploading a result file a hash of the data is logged. Since a hash changes if a result is altered or deleted, this can prove **data integrity** should it ever being questioned. +* The study log is only as safe as the server machine on which JATOS is running. Anybody with access to the server can potentially modify the study log file and e.g. hide that data has been deleted. We can't prevent this, so it's important to have a safe server that only admins can access. +* The study log is in JSON format. Choose between **pretty** (like in the screenshot above) or **raw**. diff --git a/versioned_docs/version-3.9.1/Run_your_study/Tips-and-Tricks.md b/versioned_docs/version-3.9.1/Run_your_study/Tips-and-Tricks.md new file mode 100644 index 0000000000..cf5b1e741d --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Tips-and-Tricks.md @@ -0,0 +1,90 @@ +--- +title: Tips & Tricks +slug: /Tips-and-Tricks.html +sidebar_position: 11 +--- + +### Batch and Group Session do not work on Windows without HTTPS + +The Batch and Group Session rely on WebSockets. Sometimes (rarely) a virus scanner prohibits unencryped WebSockets. This is only a problem on Windows, but not on Mac OS or Linux and only with certain virus scanner programs. If this happens you will see an error message in your brower's console: _Batch channel closed unexpectedly_. To solve this you can either turn on HTTPS on your JATOS server (recommended) or turn off the virus scranner on (all) your participants computers. + +### Run up to 10 studies in the same browser at the same time + +When a participant runs a study they usually run only one at any given time. For them it's not necessary to run more than one study in parallel in the same browser. But during development of a study it can be an immensely useful feature especially if you are using the Batch Session or develop a group study. You can run the study in up to 10 tabs in the same browser with any worker that pleases you and all these 10 "different" workers can interact with each other. If more than 10 studies run in the same browser in parallel the oldest study is finished automatically. If you want to even more worker in parallel you can always use a different browsers: each other browser adds 10 new possible parallel-running workers. + + +### Imitate a run from Mechanical Turk + +Testing studies posted in MTurk is especially cumbersome, because you should make sure that the confirmation codes are correctly displayed when the study is over. The standard way to test this is to create a study in MTurk's [Sandbox](https://requester.mturk.com/developer/sandbox). There is a way to imitate MTurk, without having to set up anything in the sandbox. Here's how. + +If you think about it, MTurk simply calls a JATOS [study link](Run-your-Study-with-Study-Links.html), which is just an URL, something like `http://my-jatos-server/publix/tmJ4Ls83sV0` (where `tmJ4Ls83sV0` is the study code and you should change it). Two additional query parameters in the URL tell JATOS that this request comes from MTurk: `workerId` and `assignmentId`. Both pieces of information are normally generated by MTurk; but they can be any arbitrary string. + +#### Examples + +* To run the study with ID 4 and batch with ID 2 with an **MTurk** worker on a local JATOS use + + ``` + http://localhost:9000/publix/myStudyCode?workerId=123456&assignmentId=abcdef + ``` + + You can use any arbitrary value in the query parameter `workerId` and `assignmentId` (in this example, `workerId = 12345` and `assignmentId = abcdef`). And you have to change the study code `myStudyCode` to one of your study. + +* To imitate a run from **MTurk's Sandbox** additionally set `turkSubmitTo` to the value 'sandbox': + + ``` + http://localhost:9000/publix/myStudyCode?workerId=123456&assignmentId=abcdef&turkSubmitTo=sandbox + ``` + + +### Lock your studies before running them + +Each Study bar has a button that toggles between the 'Unlocked' and 'Locked' states. Locking a study prevents changes to its (or any of its components') properties, change the order of components, etc. + +![](/img/v39x/study_locked.png) + + +### Do a General Single run more than once in the same browser + +The problem here is that a General Single Run is intended to work only once in the same browser. Although this is a feature to limit participants doing the same study twice, it can be a hassle for you as a study developer who just want to try out the General Single Run a second time. Luckily there is an easy way around: Since for a General Single Run all studies that the worker already participated in are stored in a browser cookie, it can be easily removed. Just **remove the cookie with the name JATOS_GENERALSINGLE_UUIDS** in your browser. You can find this cookie in every webpage hosted by a JATOS server. If it doesn't exist you probably never did a General Single run yet. + + +### Abort study and keep some data + +If the `jatos.abortStudy` function is called (usually after the worker clicks a "Cancel" button) all result data that had been sent to JATOS during this study run will be deleted. This includes result data from prior components of the study run. But sometimes you'll want to save a bit of information that should not be deleted: you might need the worker's email address to pay them. + +1. By using the build-in abort button with [`jatos.addAbortButton`](jatos.js-Reference.html#jatosaddabortbutton) and set the `msg` parameter. This message won't be deleted together with the other result data. This message can then be seen in every Study Result page in the 'Message' column. + + E.g. + + ``` + jatos.addAbortButton({ + msg: "participants ID is 12345678", + }); + ``` + +1. By using [`jatos.abortStudy`](jatos.js-Reference.html#jatosabortstudy) and its message parameter. This message won't be deleted together with the other result data. This message can then be seen in every Study Result page in the 'Message' column. + + E.g. + + ``` + jatos.abortStudy("participants ID is 12345678"); + ``` + + +### How to let a Personal Single worker redo his study? + +A Personal Single Worker is only allowed to run their study once. But sometimes you want to allow them to do it a second time (maybe they accidentally clicked the 'Cancel' button). One way would be to just create another Personal Single Link and hand it to the worker. But there is another way without creating a second Link: you can simply delete the worker's result from one of the result pages. This will allow this Personal Single worker to redo this study. + +### Simulate slow network + +Usually one develops a study on a local JATOS or a remote JATOS with a good internet - but your participants might live at a place where internet connections are slower or run your study via mobile network. All studies should take this into account, but especially those with big files like images, audio or video. There is a way to artifically throttle the network speed in [Firefox's](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) and [Chrome's](https://developers.google.com/web/tools/chrome-devtools/network#throttle) Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote. + +### Personal/General Single links seem not to work when distributed via social networks + +Problem: The study runs fine, but as soon as one distributes links for Personal Single or General Single runs via social networks like Twitter, Facebook and Reddit or chat tools like Slack and Google Hangout it stops working. The participants only get the message 'A problem occurred: Study can be done only once.' and in the results the study run appears as started but never finished (State DATA_RETRIEVED). + +The reason for this behaviour is that some of those tools open links that are posted in them before your participant can click on them. They do this to provide more information about the link, like a title and an image. Usually this is fine but Personal/General Single links work exactly once (if preview is not allowed) and a second request with the same link just responses with the forementioned error message. + +1. Use [study links with confirmation](Run-your-Study-with-Study-Links.html#study-links---how-to-let-participants-run-your-study) - Choose the study link version with the button 'Confirm First'. This link shows a 'study entry' page before the actual study starts. This page can be opened many times. + +1. [Allow preview](Restricting-study-flow.html#allow-preview) - You can keep using Personal/General Single links and use a [preview link](Restricting-study-flow.html#preview-links) to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again. diff --git a/versioned_docs/version-3.9.1/Run_your_study/Use-Prolific.md b/versioned_docs/version-3.9.1/Run_your_study/Use-Prolific.md new file mode 100644 index 0000000000..c5ea5b2318 --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Use-Prolific.md @@ -0,0 +1,62 @@ +--- +title: Use Prolific +slug: /Use-Prolific.html +sidebar_position: 6 +--- + +It is very easy to use JATOS together with [Prolific](https://www.prolific.co/) to recruit participants. + +It's pretty simple: To connect JATOS with Prolific, you have to (1) tell Prolific where to send participants to run the JATOS study and (2) tell JATOS where to send people back to Prolific, so they get paid when they finish the study. + +First, find your _Project_ page in Prolific. + +### 1. In Prolific: Enter your JATOS study link + +Here is a screenshot of how it looks in Prolific: + +![Prolific screenshot](/img/prolific_1_studyurl.png) + +In the field under _What is the URL of your study?_ (in the screenshot above), enter a link to your JATOS study. You probably want a study link of either _General Single_ or a _General Multiple_ type (see [Run your Study with Study Links](Run-your-Study-with-Study-Links.html)). + +Also, we recommend you click the option that you'll use URL parameters. This will modify the JATOS study link you entered -- that's fine. + +### 2. In JATOS: Redirect to Prolific's end page after the study is done + +Get the redirect link from your _Project_ page in Prolific…: + +![Prolific screenshot](/img/prolific_2_redirectlink.png) + +And copy it into the **End Redirect URL** field of your Study Properties in JATOS: + +![screenshot](/img/v39x/end-redirect-url.png) + + + +## Bonus (Optional) + +You can connect JATOS and Prolific programmatically through query parameters and JS. + +### 1. Consider passing Prolific URL parameters to your study + +Prolific allows you to pass the parameters PROLIFIC PID, STUDY ID, and SESSION ID as URL parameters. You just need to make sure you cliked the radio button "I'll use URL parameters on Prolific" (see the screenshot from point 1). + +You will then be able to access those URL parameters in your study's JavaScript via [`jatos.urlQueryParameters`](jatos.js-Reference.html#jatosurlqueryparameters). + +### 2. Consider redirecting participants from within JS + +Step 2 above, where you use the JATOS GUI to tell JATOS about the redirect link to Prolific, is the easiest and recommended. In some cases you might want to do with within your JS. + +With _jatos.js_: Include [`jatos.endStudyAndRedirect`](jatos.js-Reference.html#jatosendstudyandredirect) in the JavaScript of your **last** component + + E.g. but change this URL to the one you see in Prolific + + ```javascript + jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD"); + ``` + + You can combine it with sending result data + + ```javascript + var resultData = {id: 123, data: "my important result data"}; + jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData); + ``` diff --git a/versioned_docs/version-3.9.1/Run_your_study/Worker-Types.md b/versioned_docs/version-3.9.1/Run_your_study/Worker-Types.md new file mode 100644 index 0000000000..5c0076fdb9 --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/Worker-Types.md @@ -0,0 +1,66 @@ +--- +title: Worker Types +slug: /Worker-Types.html +sidebar_position: 3 +--- + +### Overview +Following Amazon Mechanical Turk’s terminology, a worker in JATOS is a person who runs a study. Different worker types access a study in different ways. For example, some workers can run the same study multiple times, whereas others can do it only once. + +| | Jatos | Personal Single | Personal Multiple | General Single | General Multiple | MTurk (Sandbox) | +|-|-------------------|-------------------|-------------------|-------------------|-------------------|------------------| +| **Typical use** | During study development | Small targeted group, each one of them gets a link | Small targeted group of workers who pilot the study or need to do it multiple times | Bigger groups but with less control; link shared e.g. via social media | Bigger groups and where the workers need to do it multiple times | For Amazon Mechanical Turk | +| **Created when?** | Together with the JATOS user | When you create the link | When you create the link | On-the-fly whenever someone uses the link | On-the-fly whenever someone uses the link | On-the-fly after a MTurk worker clicked on the HIT link | +| **Repeat the same study with the same link** | (has no links) | | (keeps the same worker) | | (creates a new worker each time)| | +| **Run different studies with the same worker** | | | | | | | +| **Supports [preview of studies](Worker-Types.html#preview-links)** | | | | | | | +| **Possible bulk creation** | | | | | | | +| **Run [group studies](Example-Group-Studies)** | | | | | | | + + +### Jatos Worker + +**Jatos workers can run any study as many times as they want.** + +Jatos workers run a study (or any of its components individually) by clicking on the _Run_ buttons in the GUI. Jatos workers are usually the **researchers trying out their own studies**. Each JATOS user (i.e., anybody with a JATOS login) has their own Jatos worker. They are not meant to be used by participants. + + +### Personal Single Worker + +With a Personal Single study link **a study can be run only once** ([*But see Allow Preview](Restricting-study-flow.html#allow-preview)). You can think of them as _personalized links with single access_. Each Personal Single study link corresponds to a Personal Single worker. + +Usually you would send a Personal Single study link to workers that you contact individually. Personal Single study links are useful in small studies, where it's feasible to contact each worker individually, or (e.g.) you want to be able to pair up several results (either from the same or different studies) in a longitudinal design. + +[More about how to generate Personal type study links](Run-your-Study-with-Study-Links.html#personal-type-links) + + +### Personal Multiple Worker + +With a Personal Multiple study link the worker can **run a study as many times as they want**. Each Personal Multiple study link corresponds to a Personal Multiple worker. + +You could send Personal Multiple study links to your pilot workers. + +[More about how to generate Personal type study links](Run-your-Study-with-Study-Links.html#personal-type-links) + + +### General Single Worker + +This study link type can be used **many times by different participants to run a study but only once per browser** ([*But see Allow Preview](Restricting-study-flow.html#allow-preview)). Each time the link is used a new General Single worker is created on-the-fly. + +You could distribute a General Single study link through social media, like twitter, a mailing list or posting it on a public website. It is essentially useful for cases where you want to collect data from a large number of workers. + +Keep in mind, however, that JATOS uses the browser's cookies to decide whether a study link was already used. If someone uses a different computer, a new browser, or simply deletes their browser's cookies, then JATOS will assume that it's an unused study link. So the same person could (with some effort) use a General Single link several times. + + +### General Multiple Worker + +A General Multiple study link is the least restrictive type and can be used **many times by different participants to run a study**. The difference to a General Single is that the General Multiple study link can be used repeatedly **even in the same browser**. Each time a General Multiple study link is used a new General Multiple worker is created on-the-fly. + + +### MTurk (Sandbox) Worker + +MTurk and MTurk Sandbox workers access a JATOS study through a study link in Amazon's Mechanical Turk (MTurk). + +[More about MTurk study links](Connect-to-Mechanical-Turk.html) + +**DATA PRIVACY NOTE:** If the same worker from MTurk does two of your studies, the two results will be paired with the same MTurk worker in JATOS. This means that you could gather data from different studies, without your workers ever consenting to it. For this reason, we recommend that you delete your data from JATOS as soon as you finish a study. This way, if the same worker from MTurk takes part in a different study, they will get a new MTurk worker, and you will not be able to automatically link their data between different studies. See our [Data Privacy and Ethics](Data-Privacy-and-Ethics) page for more details on this. diff --git a/versioned_docs/version-3.9.1/Run_your_study/_category_.json b/versioned_docs/version-3.9.1/Run_your_study/_category_.json new file mode 100644 index 0000000000..65f0dc752c --- /dev/null +++ b/versioned_docs/version-3.9.1/Run_your_study/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Run your study", + "position": 3 +} diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/Bring-your-JATOS-online.md b/versioned_docs/version-3.9.1/Serving_the_Internet/Bring-your-JATOS-online.md new file mode 100644 index 0000000000..67845c5383 --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/Bring-your-JATOS-online.md @@ -0,0 +1,37 @@ +--- +title: Bring your JATOS online +slug: /Bring-your-JATOS-online.html +sidebar_position: 1 +--- + +If you want participants to be able to run your studies you have to bring JATOS online, into the Internet. There are different ways to do this, each with its own pros and cons and we discuss these way in depth on their own page. Now here is already an overview: + +| | Setup time | Setup difficulty | Cost | Number of JATOS user / JATOS workers | Expected running time span | Reliability | Privacy | +|-------------------|-------------------|-------------------|-------------------|-------------------| +| **[1. Expose your local JATOS](#1-expose-your-local-jatos-to-the-internet)** | fast | easy | none | you / few † | hours to few days | medium to low | as good as your computer | +| **[2. Cloud server](#2-cloud-server)** | fast to medium | depends on your vendor | yes | many / many ‡ | hours to years | high | medium | +| **[3. Own server](#3-own-server)** | medium to slow (depends on your IT) | needs admin skills | ask your IT | many / many ‡ | month to years | high | high | + +†) Depends on your computer and Internet connection +‡) Depends on your server + + +## 1. Expose your local JATOS to the Internet + +This is the easiest, but also least reliable way. If you just want to run an experiment online for a couple of hours or days, but it's not extremly dramatic if things break - this one is for you. + +More information: [Expose your local JATOS](Expose-your-local-JATOS.html) + +## 2. Cloud server + +Can be still fast & easy (depending on your cloud vendor and your skills), but might not be in line with your privacy principles. This one is reliable and can run for a long time (as long as you pay). And it can serve many JATOS users. + +Go on with [JATOS on DigitalOcean](JATOS-on-DigitalOcean.html) or [JATOS on AWS](JATOS-in-Amazons-Cloud-without-Docker.html) (or any other cloud vendor) + +## 3. Own server + +A JATOS installation at your institute on a dedicated server is probably the safest and most reliable way - but also the one that (usually) takes the longest time and most admin skills to set up. + +More information: [Install JATOS on a server](JATOS-on-a-server.html) + + diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/Expose-your-local-JATOS.md b/versioned_docs/version-3.9.1/Serving_the_Internet/Expose-your-local-JATOS.md new file mode 100644 index 0000000000..95942abe47 --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/Expose-your-local-JATOS.md @@ -0,0 +1,63 @@ +--- +title: Expose your local JATOS +slug: /Expose-your-local-JATOS.html +sidebar_position: 2 +--- + +## Introduction + +This page is about how to expose your locally installed JATOS to the Internet. That means using your personal computer as a server. If you want to know a bit more about the background, I recommend reading [Tunnelling services for exposing localhost to the web](https://www.chenhuijing.com/blog/tunnelling-services-for-exposing-localhost-to-the-web). There are several tunneling services and some of those are free or have at least a free offer. Here we concentrate on _ngrok_ and _localhost.run_. Both are working fine. Just pick one. If you have **Windows** and don't know SSH, _ngrok_ will suit you best since it has an installer. + +But first some general advice: +* This way to bring JATOS online is the easiest to use - but also the **least reliable** one. Your local computer is prone to accidents (e.g. unplugged power cable, interrupted Internet). If you need a more dependable JATOS look at [Bring your JATOS online](Bring-your-JATOS-online.html). +* You have to **leave your computer running** you want your participants to access your JATOS with your study. Potentially you can use your computer in the mean time, but be aware that everything might interfere with JATOS, e.g. a crashed OS stops JATOS too. Better let your computer run in peace for the duration of your study. +* Find more reliable [ways to bring your JATOS online](Bring-your-JATOS-online.html) + + +## ngrok + +1. Download & setup ngrok: [https://ngrok.com/download](https://ngrok.com/download) + +1. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without. + +1. Start your local JATOS + +1. In your terminal move to the directory where you installed ngrok and start it with: + + ```shell + ./ngrok http 9000 + ``` + + The output should look similar to this: + + ![ngrok screenshot](/img/screenshot_ngrok.png) + +1. Copy & Paste the URL with _https_ to your browser and check that JATOS is running properly with JATOS' build-in [tests](/Troubleshooting.html#jatos-test-page). + +1. That's all. Now you can [create study links](Run-your-Study-with-Study-Links.html) and send them to your participents. Remember to use JATOS under the _ngrog.io_ address when you create study links (and not your localhost one). + +More information on [https://ngrok.com](https://ngrok.com/). + + +## localhost.run + +1. Start your local JATOS + +1. Execute in your terminal + + ```shell + ssh -R 80:localhost:9000 ssh.localhost.run + ``` + + E.g. the output could look like: + + ```shell + $ ssh -R 80:localhost:9000 ssh.localhost.run + Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run + ``` + +1. Copy & Paste the URL with _https_ to your browser and check that JATOS is running properly with JATOS' build-in [tests](/Troubleshooting.html#jatos-test-page). + +1. That's all. Now you can [create study links](Run-your-Study-with-Study-Links.html) and send them to your participents. Remember to use JATOS under the _localhost.run_ address when you create study links (and not your localhost one). + +More information on [http://localhost.run/](http://localhost.run/). diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/Install-JATOS-via-Docker.md b/versioned_docs/version-3.9.1/Serving_the_Internet/Install-JATOS-via-Docker.md new file mode 100644 index 0000000000..abbd408460 --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/Install-JATOS-via-Docker.md @@ -0,0 +1,143 @@ +--- +title: Install JATOS via Docker +slug: /Install-JATOS-via-Docker.html +sidebar_position: 8 +--- + +JATOS' Docker images are hosted at [hub.docker.com/r/jatos/jatos/](https://hub.docker.com/r/jatos/jatos/). + +Docker is a great technology, but if you never heard of it you can safely ignore this page (it's not necessary to use it if you want to install JATOS, either locally or on a server). + +Also have a look at [JATOS with Docker Compose](/JATOS-with-Docker-Compose.html) for some advanced Docker setup. + + +## Installation with Docker + +1. In your terminal: + + * Get the latest release: + + ```shell + docker pull jatos/jatos:latest + ``` + + * or a specific [release](https://hub.docker.com/r/jatos/jatos/tags) (exchange _x.x.x_ with the version): + + ```shell + docker pull jatos/jatos:x.x.x + ``` + +1. Run JATOS (change _latest_ to your version) + + ```shell + docker run -d -p 80:9000 jatos/jatos:latest + ``` + + The `-d` argument specifies to run this container in detached mode (in the background) and the `-p` is responsible for the port mapping. + +1. You can check that the new container is running correctly: + + In the following instructions, if you are on a remote host, change `127.0.0.1` to your IP/domain. + + * Use `docker ps` in the terminal: in the line with `jatos/jatos` the status should say `up` + * Use curl: `curl http://127.0.0.1/ping` should give you `pong` back + * In a browser go to [http://127.0.0.1](http://127.0.0.1) - it should show the JATOS login screen + * Check JATOS' administration page: [http://127.0.0.1/jatos/admin](http://127.0.0.1/jatos/admin) + * Run the _Tests_: all should show an 'OK' + * Check the _System Info_ that it is all like you configured it + +1. Always change the admin's password after first installation: Go to [http://127.0.0.1/jatos/user/admin](http://127.0.0.1/jatos/user/admin) and and press button _Change Password_. + + +## Debugging and Troubleshooting + +To get the logs add the argument `-Djatos.logs.appender=ASYNCSTDOUT` and run the container not detached: + +```shell +docker run -p 9000:9000 jatos/jatos:latest -Djatos.logs.appender=ASYNCSTDOUT +``` + + +## Change port + +With Docker you can easily change JATOS' port (actually we change the port mapping of JATOS' Docker container). Just use _docker_'s `-p` argument and specify your port. E.g. to run JATOS on standard HTTP port 80 use: + +``` shell +docker run -d -p 80:9000 jatos/jatos:latest +``` + + +## Configuration with Docker + +JATOS running in a Docker container can be configured the same way as running it the normal way: via a configuration file, via environment variables, or command line arguments. Have a look at [JATOS Configuration](/JATOS_Configuration.html) for the possibilities. + + +### Via arguments + +Add as many arguments to the end of the _docker_ command as you wish. + +E.g. to run JATOS with a MySQL database running on localhost (not in a container), with the default port 3306, use the following command (change username and password to your MySQL user): + +```shell +docker run -d --network="host" jatos/jatos:latest \ + -Djatos.db.url='jdbc:mysql://localhost/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' \ + -Djatos.db.username='jatosuser' \ + -Djatos.db.password='my-password' \ + -Djatos.db.driver='com.mysql.cj.jdbc.Driver' +``` + + +### Via environment variables + +All environment variables that can be used to [configure a normal JATOS server installation](JATOS_Configuration.html) can be used in a Docker installation. Just use _docker_'s `-e` argument to set them. + +E.g. to run JATOS with a MySQL database running on localhost (not in a container), with the default port 3306, use the following command (change username and password to your MySQL user): + +~~~ shell +docker run -d --network="host" \ + -e JATOS_DB_URL='jdbc:mysql://localhost/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' \ + -e JATOS_DB_USERNAME='jatosuser' \ + -e JATOS_DB_PASSWORD='my-password' \ + -e JATOS_DB_DRIVER='com.mysql.cj.jdbc.Driver' \ + jatos/jatos:latest +~~~ + + +### Via configuration file + +You can mount a configuration file (_jatos.conf_) as a Docker [_volume_](https://docs.docker.com/storage/volumes/) in the container. This way you can comfortably edit the _jatos.conf_ in your local file system. + +E.g. with a _jatos.conf_ in the current working directory: + +```shell +docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest +``` + + +## Persist data with _volumes_ + +[_Volumes_](https://docs.docker.com/storage/volumes/) are the preferred way to persist data with Docker containers. This can be necessary if one wants to update JATOS or do backups. + +Before using a _volume_ one has to create it: + + +```shell +docker volume create --name jatos_data +``` + +In JATOS' Docker container all data are stored, by default, in the folder `/opt/jatos_data` (although this can be configured). Now you can mount the newly created _volume_ _jatos_data_ at this location: + +```shell +docker run -d -p 9000:9000 --volume jatos_data:/opt/jatos_data jatos/jatos:latest +``` + + +## Updating JATOS with Docker + +**Be aware**: JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation. Please do backups before updating. + +There are two possibilities to update JATOS running in a Docker container: + +1. Unless you run [JATOS on multiple nodes](/JATOS-in-a-cluster.html), you can simply use the [auto-update feature](/Update-JATOS.html#automatic-update) to update JATOS to newer versions. + +1. Another way, arguably even simpler, is to just change the Docker image tag of JATOS to a newer version. Stop the current running JATOS container and run a new one with the new version tag. **But this only works if you [persist your data with volumes](/Install-JATOS-via-Docker.html#persist-data-with-volumes) - If you don't use volumes your data stored in JATOS will be lost**. diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md new file mode 100644 index 0000000000..662db2853c --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md @@ -0,0 +1,19 @@ +--- +title: JATOS on AWS +slug: /JATOS-in-Amazons-Cloud-without-Docker.html +sidebar_position: 6 +--- + +On this page is additional information in how to install JATOS on a server on AWS. All general installation advice is in [JATOS on a server](JATOS-on-a-server.html) and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for [Apache](/JATOS-with-Apache.html) or [Nginx](/JATOS-with-Nginx.html). If you are looking for an easier way to install JATOS in the cloud, the tutorial [JATOS on DigitalOcean](JATOS-on-DigitalOcean.html) might be what you are looking for. + +1. First you need to register at [AWS](https://aws.amazon.com/) (they'll want your credit card). +1. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too) +1. During the creation of the new EC2 instance you will be ask whether you want to create a key pair. Do so. Download the file with the key (a *.pem file). Store it in a safe place - with this key you will access your server. +1. Login via SSH: `ssh -i /path/to/your/pem_key_file ubuntu@xx.xx.xx.xx` (Use your instance's IP address: In AWS / EC2 / Instances / Description are two IPs 'Private IP' and 'Public IP'. Use the **public** one.) +1. Get the latest JATOS: either bundled with Java `wget https://github.com/JATOS/JATOS/releases/latest/download/jatos_linux_java.zip` or without `wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip`. In the latter case you have to install Java yourself. +1. `unzip jatos_linux_java.zip` (You probably have to install 'unzip' first with `sudo apt-get install unzip`.) +1. If you do **not** use a reverse proxy like [Nginx](/JATOS-with-Nginx.html) or [Apache](/JATOS-with-Apache.html) you have to configure IP and port in `conf/jatos.conf` (or `conf/production.conf` in version < 3.8.3): Use the '**Private IP**' from your instance description (the one that starts with 172.x.x.x) and port 80 +1. Allow inbound HTTP/HTTPS traffic: [This is done in AWS GUI](https://aws.amazon.com/premiumsupport/knowledge-center/connect-http-https-ec2/). +1. (Optional) [auto-start JATOS](/JATOS-on-a-server.html#optional-auto-start-jatos-via-systemd) +1. Change JATOS' admin password + diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-a-cluster.md b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-a-cluster.md new file mode 100644 index 0000000000..0719c74a1c --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-in-a-cluster.md @@ -0,0 +1,232 @@ +--- +title: JATOS in a cluster +slug: /JATOS-in-a-cluster.html +sidebar_position: 10 +--- + +JATOS can run on multiple nodes in a cluster to achieve high availability and scalability. + +## Things to know before running JATOS in a multi-node setup + +* JATOS, in a multi-node setup, needs a **MySQL** or **MariaDB** database (and cannot be used with the embedded H2 database). +* All JATOS nodes need to **share some folders**: _study assets_, _study uploads_, _study logs_, and JATOS' _tmp_ folder. +* All JATOS nodes need the **same secret**, otherwise the session cookie used for authentication won't work. +* **Updating** is arguably easier by just changing the tag of JATOS docker image to a higher version (but JATOS' auto-updater can't be used). + +All these points (and more) are addressed in this page. + + +## Multi-node installation with Docker Compose + +A setup of JATOS with multiple nodes through [Docker Compose](https://docs.docker.com/compose/) might not make much sense, because all JATOS instances still run on the same machine. But it highlights some general concepts and caveats pretty well, so we describe it here. + +How to get started with JATOS and Docker Compose is explained in [another page](/JATOS-with-Docker-Compose.html). You might want to follow the instructions there to get a JATOS installation with a MySQL database and Nginx running. + +Now, if you want to run JATOS in multiple containers in parallel you need to configure the [_compose.yaml_](https://github.com/JATOS/JATOS_with_docker_compose/blob/main/compose.yaml) additionally (if you haven't already): + +1. Set **`-Djatos.multiNode=true`** in the _command_ section of the _jatos_ service. +1. Set the **`JATOS_SECRET`** environment variable to a string with at least than 15 characters (otherwise the session cookie that JATOS uses for authentication won't work). + +It's important to share some of JATOS folders between all JATOS nodes. In our Docker composed setup this is already achieved with the shared _volumes_ _jatos-data_, _jatos-logs_, and _jatos-db_. Nothing to do here. + +Finally, to scale up and run multiple JATOS instances use the `--scale` parameter, e.g. to run two JATOS instances: + +```shell +docker compose -f compose.yaml up --scale jatos=2 +``` + + +## JATOS with Kubernetes + +[Kubernetes](https://kubernetes.io/) is a system for container orchestration and automatic deployments. It offers vast possibilities to do so in many different ways that might also depend on your cloud provider. Here we used it with [DigitalOcean](https://docs.digitalocean.com/products/kubernetes/) - but with some adjustments it should work on any Kubernetes cluster. + +For the JATOS cluster we use [Kustomize](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/kustomization/) to define Kubernetes objects through _kustomization_ YAML files. + +We assembled all necessary files in a [git repository](https://github.com/JATOS/JATOS_with_kubernetes). + +```shell +git clone https://github.com/JATOS/JATOS_with_kubernetes.git +``` + +The file [_kustomization.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/kustomization.yaml) defines our secrets and specifies the resource file, [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml), that describes the JATOS cluster. + +Then, after you set up everything, you can start the cluster with: + +```shell +kubectl apply -k +``` + + +### Load-balancing and scaling + +In our [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml), for _auto-balancing_ in our JATOS cluster, we use the one [integrated in DigitalOcean](https://docs.digitalocean.com/products/kubernetes/how-to/add-load-balancers/). This is specified in the _Service_ object, with the _annotation_ `kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer"`. + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: jatos + labels: + app: jatos + annotations: + kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer" +spec: + ports: + - port: 80 + targetPort: 9000 + selector: + app: jatos + type: LoadBalancer +``` + +And our cluster does _automatic horizontal scaling_ with an `HorizontalPodAutoscaler`. Here we set up a minimum of 2 and maximum of 10 JATOS pods and as scaling metric a average CPU utilization of 100%. + +```yaml +apiVersion: autoscaling/v2 +kind: HorizontalPodAutoscaler +metadata: + name: jatos +spec: + scaleTargetRef: + apiVersion: apps/v1 + kind: Deployment + name: jatos + minReplicas: 2 + maxReplicas: 10 + metrics: + - type: Resource + resource: + name: cpu + target: + type: Utilization + averageUtilization: 100 +``` + + +### Shared volumes + +As said [before](/JATOS-in-a-cluster.html#things-to-know-before-running-jatos-in-a-multi-node-setup), JATOS, if running on multiple nodes, needs to share some folders. Translated to Kubernetes this means the _PersistentVolumeClaim_ needs the `accessMode`: `ReadWriteMany`. + +Although many cloud provider have their own storage system to achieve this, we use a common _NFS_ storage. E.g. there is an easy-to-use [helm chart](https://helm.sh/) for this purpose: [nfs-server-provisioner](https://artifacthub.io/packages/helm/kvaps/nfs-server-provisioner). And since we want to run on _DigitalOcean_ we need the parameter `persistence.storageClass` set to `do-block-storage`. + +```shell +helm install nfs-server stable/nfs-server-provisioner --set persistence.enabled=true,persistence.storageClass=do-block-storage,persistence.size=11Gi +``` + +Then in our [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml) the NFS storage is used in a `PersistentVolumeClaim`: + + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: jatos-data-pv-claim + labels: + app: jatos +spec: + accessModes: + - ReadWriteMany + resources: + requests: + storage: 10Gi + storageClassName: nfs +``` + +And the _volume_ is mounted in every JATOS _pod_: + +```yaml +volumes: + - name: jatos-data-storage + persistentVolumeClaim: + claimName: jatos-data-pv-claim +``` + +### Configure JATOS' deployment + +In [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml), to run JATOS in on multiple nodes in a cluster you have to set the parameter `-Djatos.multiNode=true`. Also the parameter `-Djatos.logs.appender=ASYNCSTDOUT` redirects the logging to _stdout_, which is what you probably want with Kubernetes. + +The parameter `-J-Xmx` defines the maximum memory the Java Virtual Machine (JVM) that runs JATOS is allowed to use. If you don't set this, the JVM might take too much memory for itself and strangle the operating system. Here we set it to 1500 MB but it really depends on the kind of underlying machine you are using to run your nodes. + +You might want to change the Docker image version to a different one. + +```yaml +containers: + # Maybe use a newer image version + - image: jatos/jatos:3.8.4 + name: jatos + args: + # Necessary to run JATOS on multiple nodes + - -Djatos.multiNode=true + # Logging to stdout + - -Djatos.logs.appender=ASYNCSTDOUT + # Set the JVM maximum memory usage. It has to fit your machine. + - -J-Xmx=1500M +``` + +### Secrets + +The password for the MySQL database and the secret for JATOS session cookie are set in the [`kustomization.yaml`](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/kustomization.yaml) file and then just referenced in [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml) in JATOS _deployment_ object. + + +### MySQL setup + +We assume here that you have your MySQL database set up and ready already. Have a look at [JATOS with MySQL](/JATOS-with-MySQL.html) to get started. + +In [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml) you have to change the environmental variable `JATOS_DB_URL`. The IP and port need to be the ones from your MySQL IP and port. + + +### Liveness probe and startup probe + +Applications running on the JVM can need some initial warm-up time before they are fully functional. Therefore we have, additionally to the `livenessProbe` in [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml), a `startupProbe` that accounts for this. You might have to tweak `failureThreshold` and `periodSeconds` on your system. + +```yaml +livenessProbe: + httpGet: + path: /ping + port: 9000 + failureThreshold: 1 + periodSeconds: 10 +startupProbe: + httpGet: + path: /ping + port: 9000 + failureThreshold: 30 + periodSeconds: 10 +``` + + +### _securityContext_ and _affinity_ + +The [_jatos.yaml_](https://github.com/JATOS/JATOS_with_kubernetes/blob/main/jatos.yaml) also has a _securityContext_ and a _affinity_ section. You probably don't have to change anything there. We just want to explain them here shortly. + +The _securityContext_ sets the _UID_ and _GID_ of the user defined in JATOS' Docker image. + +```yaml +securityContext: + runAsUser: 1000 + runAsGroup: 1000 + fsGroup: 1000 +``` + +In the _affinity_ section we define a `podAntiAffinity` to ensure that each Kubernetes _pod_ runs only one JATOS. + +```yaml +affinity: + podAntiAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - topologyKey: kubernetes.io/hostname + labelSelector: + matchLabels: + app: jatos +``` + + +### Updating JATOS with Kubernetes + +The easiest way to update a JATOS Kubernetes cluster is to **just change the JATOS' Docker image tag to a higher version**. [JATOS' auto-updater](/Update-JATOS.html#automatic-update) **cannot** be used here. + +But there are some **constraints**: + +1. Kubernetes' _rolling updates_ are not possible with JATOS. You have to turn off all JATOS pods, do the update (change the Docker image tag) and turn them back on. +1. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation. +1. And please do backups before updating. diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-on-DigitalOcean.md b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-on-DigitalOcean.md new file mode 100644 index 0000000000..f074112e6e --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-on-DigitalOcean.md @@ -0,0 +1,190 @@ +--- +title: JATOS on DigitalOcean +slug: /JATOS-on-DigitalOcean.html +sidebar_position: 5 +--- + +Here we explain how to install JATOS in the cloud by using [DigitalOcean](https://www.digitalocean.com). DigitalOcean is a cloud provider (like _AWS_, _Google Cloud_, _Azure_ etc.). We provide this example because DigitalOcean is comparatively easy to use and has good documentation - but we have no connection to DigitalOcean whatsoever. + +**Keep in mind: A server in the cloud will cost money (depending on the size $5 to $50 / month (and more)) and to open an account with DigitalOcean you will need a credit card.** + + +## Set up a simple JATOS server on DigitalOcean + +First we want to set up a simple JATOS server without encryption (HTTPS) or a domain name. + +DigitalOcean offers something called _Droplet_, that is basically a virtual machine, and we want to use it as a server for JATOS. If everything runs smoothly you don't have to use the terminal at all. You can watch the video here or follow the instructions further down. + +import ReactPlayer from 'react-player' + + + +1. Set up an account with [DigitalOcean](https://www.digitalocean.com/) - you'll have to provide billing information. + +1. Create a _Droplet_ (this is what DigitalOcean calls a virtual machine that we want to use as a server). + +1. Choose the _Region_ that is nearest to your users. + +1. Choose an image from _Marketplace_: select one with _Docker_ on _Ubuntu_ pre-installed. + +1. Choose a _Size_: For _Droplet type_ often _Basic_ is enough and for _CPU options_: _Regular_. Choose memory 1 to 4 GB according to your expected server load. Don't spend to much time on this, choose the smaller one - you can increase the size later on. If you just want to try it out: a _Regular_ with 1GB for will do it. + +1. Choose an _authentication method_ + +1. Click on _Advanced Options_ and activate _Add Initialization scripts_. Then copy+paste the following script in the text field: + + ```shell + #!/bin/bash + docker run -d --restart=always -p 80:9000 jatos/jatos:latest + ``` + + You can change 'latest' to the [specific version](https://hub.docker.com/r/jatos/jatos/tags) you need. + +1. Finally click the _Create Droplet_ button + +1. Try out your JATOS: Now the server is being created which can take a couple minutes. Copy the server's (aka Droplet) IP address into your browser's address bar and if everything went well, you will see a JATOS login screen. + +1. Log in with the default credentials 'admin' and 'admin'. + +Done! Now you have a basic JATOS server accessible from the Internet. + +**Don't forget to change your admin user's password.** Go to the admin user page (top-right corner) and and press button _Change Password_. + +DigitalOcean charges you by the second. So if you want to create a new JATOS server because something went wrong, just destroy the current one and start over again. + + +## Destroy your JATOS server + +If you want to destroy your server, go to your Droplet's page in DigitalOcean and click on _More_ -> _Destroy_. This will completely remove your JATOS server and delete all data that was collected with it. It will also delete any studies you uploaded. + + +## Set up JATOS with HTTPS and a domain + +This part is **optional** and is only necessary if you want to have your own domain name instead of an IP and use encryption (HTTPS). + +We will use [Traefik](https://github.com/traefik/traefik) as a proxy. Traefik adds encryption out-of-the-box (by using [Let’s Encrypt](https://letsencrypt.org/)) and is [open source](https://github.com/traefik/traefik) and free to use. + +**Get your own domain name**: Sorry, we can't give you a domain name - you have to get your own. But there are plenty domain name registrars that help you with this business (just search for "domain registrars"). Another option is to talk to your IT department and convince them to give you a subdomain for free. + +Now with a domain name you can encrypt your server's communication with HTTPS. + +But first a **summary of the work flow**: +1. Create droplet +1. Set up your DNS +1. Restart droplet +1. Wait until you can reach the webpage + +### Create Droplet + +To create a JATOS server with Traefik follow the instructions of the first section ([Set up a simple JATOS server on DigitalOcean](/JATOS-on-DigitalOcean.html#set-up-a-simple-jatos-server-on-digitalocean)) but in the field for the _Add Initialization scripts_ put the following script: + +```shell +#!/bin/bash + +# Change to your email and domain (for Let's Encrypt) +email=myemail@example.org +domain=my.domain.org + +cat >/root/compose.yaml < mysql_bkp.out` you can backup the whole data into a single file. Restore the database with `mysql -u myusername -p mydbname < mysql_bkp.out`. + +1. Backup H2 database + + There are at least two ways to backup an embedded H2 database: one easy (but unofficial) and one official: + + * Easy way: Just backup the _database_ folder in your JATOS installation folder. **But it is important to stop JATOS before doing a backup or restoring a H2 database** this way. If you do not stop JATOS your data might get corrupted. + + * Official way: Use [H2's upgrade, backup, and restore tool](http://www.h2database.com/html/tutorial.html#upgrade_backup_restore) + + +## Update JATOS + +**Be aware**: JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation. Please do backups before updating. + +There are two possibilities to update JATOS running on a server: + +1. You can simply use the [auto-update feature](/Update-JATOS.html#automatic-update). + +1. If you specified an extra ['data' folder](/JATOS-on-a-server.html#optional-specify-the-location-of-jatos-data-folders) you can install a new JATOS without starting it yet, stop the current JATOS, configure the new one to use your extra 'data' folder and start it. \ No newline at end of file diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Apache.md b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Apache.md new file mode 100644 index 0000000000..48d8ecfc2d --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Apache.md @@ -0,0 +1,61 @@ +--- +title: JATOS with Apache +slug: /JATOS-with-Apache.html +sidebar_position: 12 +--- + +This is an example of a configuration of [Apache](https://httpd.apache.org/) as a reverse proxy in front of JATOS. While it's not necessary to run JATOS with a proxy, it's common to do so in order to add encryption. + +It is necessary to use at least Apache **version 2.4** since JATOS relies on WebSockets that aren't supported by earlier versions. + +A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is [certbot.eff.org](https://certbot.eff.org/) from the Electronic Frontier Foundation. + +You have to add some modules to Apache to get it working: + +~~~shell +a2enmod proxy proxy_http proxy_wstunnel http2 rewrite headers ssl +~~~ + +The following is an example of a proxy config with Apache. It is stored it in `/etc/apache2/sites-available/example.com.conf` and added it to Apache with the command `sudo a2ensite example.com.conf`. Change it to your needs. You probably want to change your servers address (`www.example.com` in the example) and the path to the SSL certificate and its key. + +For JATOS versions 3.8.1 and older it is necessary to set the `X-Forwarded-*` headers with `RequestHeader set X-Forwarded-Proto "https"` and `RequestHeader set X-Forwarded-Ssl "on"` and `ProxyPreserveHost On` to tell JATOS the original requester's address. This is not necessary with version 3.8.2 and newer. + +As an additional security measurement you can uncomment the `` and config your local network. This will restrict the access to JATOS' GUI (every URL starting with `/jatos`) to the local network. + +~~~shell + + ServerName www.example.com + + # Redirect all unencrypted traffic to the respective HTTPS page + Redirect "/" "https://www.example.com/" + + + + ServerName www.example.com + + # Restrict access to JATOS GUI to local network + # + # Order deny,allow + # Deny from all + # Allow from 127.0.0.1 ::1 + # Allow from localhost + # Allow from 192.168 + # + + # Your certificate for encryption + SSLEngine On + SSLCertificateFile /etc/ssl/certs/localhost.crt + SSLCertificateKeyFile /etc/ssl/private/localhost.key + + # JATOS uses WebSockets for its batch and group channels + RewriteEngine On + RewriteCond %{HTTP:Upgrade} =websocket [NC] + RewriteRule /(.*) ws://localhost:9000/$1 [P,L] + RewriteCond %{HTTP:Upgrade} !=websocket [NC] + RewriteRule /(.*) http://localhost:9000/$1 [P,L] + + # Proxy everything to the JATOS running on localhost on port 9000 + ProxyPass / http://localhost:9000/ + ProxyPassReverse / http://localhost:9000/ + +~~~ diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Docker-Compose.md b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Docker-Compose.md new file mode 100644 index 0000000000..c8572339e3 --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Docker-Compose.md @@ -0,0 +1,123 @@ +--- +title: JATOS with Docker Compose +slug: /JATOS-with-Docker-Compose.html +sidebar_position: 9 +--- + +[_Docker Compose_](https://docs.docker.com/compose/) offers an easy way to set up a JATOS installation with a MySQL database and Nginx as an reverse proxy for, among other things, HTTPS encryption. + + +## Get started + +### Example repository + +We assembled all necessary files in a [git repository](https://github.com/JATOS/JATOS_with_docker_compose) that you can clone and then change them to your needs to get a JATOS installation running with _docker compose_. + +```shell +git clone https://github.com/JATOS/JATOS_with_docker_compose.git +``` + +The important files in the repo are _compose.yaml_ to set up _docker compose_, nginx.conf for Nginx, and jatos.conf for JATOS. + +``` +JATOS_with_docker_compose +├── compose.yaml +├── nginx.conf +├── jatos.conf +└── ... +``` + +The _docker compose_ file [_compose.yaml_](https://github.com/JATOS/JATOS_with_docker_compose/blob/main/compose.yaml) starts three services: + +1. Nginx as a reverse proxy that does encryption (HTTPS) +1. JATOS +1. A MySQL database + +Additionally it creates three shared _volumes_: + +1. _jatos-data_ - stores JATOS' data folders: _study assets_, _result uploads_, _study logs_ and JATOS' _tmp_ folder +1. _jatos-logs_ - for JATOS logs (not necessary if you log to _stdout_) +1. _jatos-db_ - where MySQL stores its data + + +### Up + +Go into the cloned folder and start the services with: + +```shell +docker compose -f compose.yaml up +``` + +If everything went smoothly, you will now see the JATOS login page under: [https://localhost/](https://localhost/) + +With `Ctrl+C` you can stop the services. Removing the stopped containers can be achieved with `docker compose -f compose.yaml down` and additionally removing all the _volumes_ by adding the `-v` flag: `docker compose -f compose.yaml down -v`. + + +### Check that it runs + +First visit the JATOS admin page: [https://localhost/jatos/admin](https://localhost/jatos/admin). There, check that all _Tests_ are OK. Also check that the _System Info_ contains the configuration you intended. + +Next, you can import a study (e.g. one from the [Example Studies](/Example-Studies)) and check if it runs well. Check, for example, that the result data appear in the results page. + +Last but not least: Check that all data are persisted: First, stop and remove the containers (but not the _volumes_!) with `docker compose -f compose.yaml down`. Then, restart the services with `docker compose -f compose.yaml up`. Now check that all studies and their result data are still there. + + +## Nginx configuration + +Have a look at [_JATOS with Nginx_](/JATOS-with-Nginx.html) and configure Nginx to your needs. The file _nginx.conf_ in our repo is mounted in Nginx' container and will be used by Nginx. + + +### Use your own certificate (for HTTPS) + +**The certificate used here in this example setup is self-signed and utterly insecure**. The certificate files are mounted as _volumes_ in the _proxy_ service. You might have to change the file names (and paths) in _nginx.conf_ too. + +```yaml +volumes: + - ./nginx-selfsigned.crt:/etc/ssl/certs/nginx-selfsigned.crt:ro + - ./nginx-selfsigned.key:/etc/ssl/private/nginx-selfsigned.key:ro +``` + + +## MySQL configuration + +The following changes should be done in the _compose.yaml_: + +Search and set `JATOS_DB_PASSWORD` and `MYSQL_PASSWORD` to the **same** password of your choice. + +Search and set `MYSQL_ROOT_PASSWORD`, MySQL's root password to one chosen by you. + +Consider to [turn off MySQL's binary log](/JATOS-with-MySQL.html#optional---deactivate-the-binary-log-of-your-mysqlmariadb) with `--skip-log-bin` in _db_'s _command_ section. + +Check [_JATOS with MySQL_](/JATOS-with-MySQL.html) for more information. + + +## JATOS configuration + +Have a look at [_JATOS Configuration_](/JATOS_Configuration.html). + +Change the image version in the _compose.yaml_ to the one you need (e.g. the latest one). + +Always change the admin's password after first installation: Go to [https://localhost/jatos/user/admin](https://localhost/jatos/user/admin) and and press button _Change Password_. + + +### Debugging and logging + +You can redirect JATOS logs to _stdout_ with `-Djatos.logs.appender=ASYNCSTDOUT` in the _command_ section of the _jatos_ service - or write the logs to a file with `-Djatos.logs.appender=ASYNCFILE` (which is actually the default and you can just leave it out). Logging to _stdout_ is useful for debugging and is also used in advanced logging solutions. If you log to _stdout_ you don't need an extra log _volume_ and you can remove _jatos-logs_. + +### Using _jatos.conf_ + +JATOS can be configured either by _command_ parameters (the ones with the `-D` prefix) in the _compose.yaml_ or with the [_jatos.conf_](https://github.com/JATOS/JATOS_with_docker_compose/blob/main/jatos.conf) configuration file. You can also set up some environment variables (like the `JATOS_DB_PASSWORD`). In the end it's up to you which way you prefer. + +The _jatos.conf_ file is mounted as a _volume_ in the JATOS container. This way you can comfortably edit your _jatos.conf_ outside of the container. + +More about [JATOS' Configuration with all possible parameters](JATOS_Configuration.html). + + +## Updating JATOS with Docker Compose + +The easiest way to update a JATOS instance running with this setup **with external data volumes** is to **just change the JATOS' Docker image tag to a higher version and restart the services**. No need to use [JATOS' auto-updater](/Update-JATOS.html#automatic-update). JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation. And please do backups before updating. + + +## Running JATOS on multiple nodes + +Have a look at [JATOS in a cluster](/JATOS-in-a-cluster.html). \ No newline at end of file diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-MySQL.md b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-MySQL.md new file mode 100644 index 0000000000..c71b237890 --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-MySQL.md @@ -0,0 +1,192 @@ +--- +title: JATOS with MySQL +slug: /JATOS-with-MySQL.html +sidebar_position: 7 +--- + +By default JATOS uses an embedded H2 database and no further setup is necessary but it can be easily configured to work with a MySQL or MariaDB database. + +Possible scenarios why one would use an external database are +* your JATOS will be used by more than a few users (e.g. several research groups or an institute-wide installation) +* your JATOS will run studies with many participants +* the expected traffic is rather high (the studies produce a lot of result data) +* you want to be able to do a regular database backup (with the embedded H2 database this would involve stopping JATOS) +* higher trust in the reliability of MySQL/MariaDB + + +## Installation + +One could install the external database on the same machine as JATOS is running or on an extra machine depending on ones need. + +**JATOS requires MySQL >= 5.7 (8.x is fine). JATOS was tested with MariaDB 10.9.7 (other versions likely work too).** + +There are many manuals out there, e.g. [this one](https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-22-04). One way to set up MySQL: + +1. Install MySQL + + E.g. on Ubuntu + + ```bash + sudo apt install mysql-server + ``` + +1. Log in to MySQL's command line terminal: + + ```bash + mysql -u root -p + ``` + +1. Create a database for JATOS: + + **Character set and collation are important - otherwise you won't have full UTF-8 support** + + ```bash + CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; + ``` + +1. Create a user for JATOS: + + ```bash + CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword'; + ``` + + Remember your username and password. You need them when configuring JATOS later on. + + Leave out the `@'localhost'` part if the database is not on the same host. + +1. Grant privileges to the new user: + + ```bash + GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost'; + ``` + +1. You can test the new user: log out of MySQL with `exit` and back in with the newly created user: + + ```bash + mysql -u jatosuser -p + ``` + +**Appart from giving JATOS access to the database it is not necessary to create any tables - JATOS is doing this automatically.** + +Now you have to configure JATOS to use your MySQL/MariaDB. + + +## Configure JATOS + +There are three ways to set up JATOS to work with a MySQL/MariaDB database. + +The properties starting with `db.default` are **deprecated** and shouldn't be used anymore. Use `jatos.db.*` instead. + +**Change IP, port, username and password** to the ones from your database. The _driver_ is always `com.mysql.cj.jdbc.Driver` for MySQL or MariaDB. + +**Always restart JATOS after making any changes to the configuration (e.g. with `./loader.sh restart`)** + +1. Via **config file** properties + + The config file, named _jatos.conf_ or _production.conf_, is located in the JATOS folder, in _./conf_ folder: + + * in `jatos.conf` (JATOS version >= 3.8.3) change the properties `jatos.db.url`, `jatos.db.username`, and `jatos.db.password`. The property `jatos.db.driver` is always `com.mysql.cj.jdbc.Driver`. + + Example: + + ~~~bash + jatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" + jatos.db.username = "jatosuser" + jatos.db.password = "mypassword" + jatos.db.driver = "com.mysql.cj.jdbc.Driver" + ~~~ + + * in `production.conf` (JATOS version < 3.8.3) change the properties `db.default.url`, `db.default.username`, and `db.default.password`. The property `db.default.driver` is always `com.mysql.cj.jdbc.Driver`. + +1. Via **command-line** arguments + + * JATOS version >= 3.8.3) set the arguments `-Djatos.db.url`, `-Djatos.db.username`, and `-Djatos.db.password` and `-Djatos.db.driver` (always `com.mysql.cj.jdbc.Driver`). + + Example: + + ~~~bash + -Djatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" + -Djatos.db.username = "jatosuser" + -Djatos.db.password = "mypassword" + -Djatos.db.driver = "com.mysql.cj.jdbc.Driver" + ~~~ + + and use them together with JATOS start command `./loader start`: + + ~~~bash + ./loader.sh start \ + -Djatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" \ + -Djatos.db.username = "jatosuser" \ + -Djatos.db.password = "mypassword" \ + -Djatos.db.driver = "com.mysql.cj.jdbc.Driver" + ~~~ + + * JATOS version < 3.8.3) set the arguments `-Ddb.default.url`, `-Ddb.default.username`, and `-Ddb.default.password` and `-Ddb.default.driver` (always `com.mysql.cj.jdbc.Driver`). + +1. Via **environment** variables + + Set the variables `JATOS_DB_URL`, `JATOS_DB_USERNAME`, `JATOS_DB_PASSWORD`, and `JATOS_DB_DRIVER` (always `com.mysql.cj.jdbc.Driver`). + + Example: + + ~~~bash + JATOS_DB_URL="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" + JATOS_DB_USERNAME='jatosuser' + JATOS_DB_PASSWORD='mypassword' + JATOS_DB_DRIVER='com.mysql.cj.jdbc.Driver' + ~~~ + +You can confirm that JATOS is accessing the correct database by opening JATOS' _Administration_ page in a browser and then click on _System Info_: The field _DB URL_ should resemble the one from your config. Another way is by looking in the logs: you should see a line after JATOS started similar to this (with your database URI): + +~~~ bash +14:06:01.760 [info] - p.a.d.DefaultDBApi - Database [default] initialized at jdbc:mysql://localhost/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC +~~~ + +Done. Your JATOS uses your MySQL/MariaDB now. + + +## Optional - Deactivate the binary log of your MySQL/MariaDB + +The binary log (also called binlog) serves two purposes: replication and data recovery. More can be found in [MariaDB's documentation](https://mariadb.com/kb/en/binary-log/). + +The problem with binary logs is that they can take up quite some disk space depending on the experiments you run on your JATOS. The location of those log files is specified in MySQL/MariaDB's config but on many systems they are under `/var/lib/mysql`. If you have a single database instance (and therefore do not use replication) and you do not need data recovery (e.g. have a different backup mechanism) than it is safe to deactivate the binary logs. + +Add `skip-log-bin` to the end of your MySQL/MariaDB config ([details](https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#option_mysqld_log-bin)). On many Linux systems the config is in `/etc/mysql/mysql.conf.d/mysqld.cnf`. + +The part of your _mysqld.cnf_ that configures the binary logs could then look similar to this: + +```bash +# The following can be used as easy to replay backup logs or for replication. +# note: if you are setting up a replication slave, see README.Debian about +# other settings you may need to change. +# server-id = 1 +# log_bin = /var/log/mysql/mysql-bin.log +# binlog_expire_logs_seconds = 2592000 +# max_binlog_size = 100M +# binlog_do_db = include_database_name +# binlog_ignore_db = include_database_name +skip-log-bin +``` + +You have to restart MySQL/MariaDB for the changes to take effect. + + +## Optional - Increase _max_allowed_packet_ size in older MySQL/MariaDB databases + +If you have an older MySQL (< 8.x.x) and your experiments will have large result data you might want to increase the _[max_allowed_packet](https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet)_ size. If your result data is larger than the _max_allowed_packet_ JATOS will just return an 'internal server error'. In JATOS' log in will look similar to this: + +``` +[ERROR] - g.ErrorHandler - Internal JATOS error +[ERROR] - o.h.e.j.s.SqlExceptionHelper - Packet for query is too large (5,920,824 > 4,194,304). You can change this value on the server by setting the 'max_allowed_packet' variable. +[WARN] - o.h.e.j.s.SqlExceptionHelper - SQL Error: 0, SQLState: S1000 +``` + +In MySQL, from 8.x.x on, the _max_allowed_packet_ is by default 64MB and this is usually more than enough. But in MySQL versions before 8 it is just 4MB by default and before 5.6.6 it's just 1MB. + +To increase the _max_allowed_packet_ size just add it to the end of your MySQL/MariaDB config. On many Linux systems the config is in `/etc/mysql/mysql.conf.d/mysqld.cnf`. E.g. to set it to 64MB: + +```bash +max_allowed_packet=64M +``` + +You have to restart the database for the changes to take effect. diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md new file mode 100644 index 0000000000..48fd40abce --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md @@ -0,0 +1,113 @@ +--- +title: JATOS with Nginx +slug: /JATOS-with-Nginx.html +sidebar_position: 11 +--- + +Here is an example for a configuration of [Nginx](https://www.nginx.com/) as a reverse proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common. + +A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is [certbot.eff.org](https://certbot.eff.org/) from the Electronic Frontier Foundation. + +The following config is the content of `/etc/nginx/nginx.conf`. Change it to your needs. You probably want to change your servers address (`www.example.com` in the example) and the path to the SSL certificate and its key. + +For JATOS versions 3.8.1 and older it is necessary to set the `X-Forwarded-*` headers with `proxy_set_header` to tell JATOS the original requester's IP address. This is not necessary from 3.8.2 and newer. + +As an additional security measurement you can uncomment the `location /jatos` and config your local network. This will restrict the access to JATOS' GUI (every URL starting with `/jatos`) to the local network. + +~~~ shell +user www-data; +pid /run/nginx.pid; +worker_processes auto; +worker_rlimit_nofile 65535; + +# Load modules +include /etc/nginx/modules-enabled/*.conf; + +events { + multi_accept on; + worker_connections 65535; +} + +http { + sendfile on; + tcp_nopush on; + client_max_body_size 500M; + + # MIME + include mime.types; + default_type application/octet-stream; + + # Logging + access_log off; + error_log /var/log/nginx/error.log warn; + + proxy_buffering off; + proxy_set_header Host $http_host; + proxy_http_version 1.1; + + # Needed for websockets + map $http_upgrade $connection_upgrade { + default upgrade; + '' close; + } + + # Load configs + include /etc/nginx/conf.d/*.conf; + + upstream jatos-backend { + server 127.0.0.1:9000; + } + + # Redirect http to https + server { + listen 80; + # --> Change to your domain <-- + server_name www.example.com; + rewrite ^ https://www.example.com$request_uri? permanent; + } + + server { + listen 443 ssl http2; + # --> Change to your domain <-- + server_name www.example.com; + keepalive_timeout 70; + + # Encryption + # --> Change to your certificate <-- + ssl_certificate /etc/ssl/certs/localhost.crt; + ssl_certificate_key /etc/ssl/private/localhost.key; + ssl_protocols TLSv1.2 TLSv1.3; + + # WebSocket location (JATOS' group and batch channel and the test page) + location ~ "/(jatos/testWebSocket|publix/[a-z0-9-]+/(group/join|batch/open))" { + proxy_pass http://jatos-backend; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + proxy_connect_timeout 7d; # Keep open for 7 days even without any transmission + proxy_send_timeout 7d; + proxy_read_timeout 7d; + } + + # Restrict access to JATOS' GUI to local network, e.g. 192.168.1.* + # location /jatos { + # allow 192.168.1.0/24; + # deny all; + # proxy_pass http://jatos-backend; + # proxy_connect_timeout 300; + # proxy_send_timeout 300; + # proxy_read_timeout 300; + # send_timeout 300; + # } + + # All other traffic + location / { + proxy_pass http://jatos-backend; + proxy_connect_timeout 300; + proxy_send_timeout 300; + proxy_read_timeout 300; + send_timeout 300; + } + } +} +~~~ \ No newline at end of file diff --git a/versioned_docs/version-3.9.1/Serving_the_Internet/_category_.json b/versioned_docs/version-3.9.1/Serving_the_Internet/_category_.json new file mode 100644 index 0000000000..ac8dc8b2db --- /dev/null +++ b/versioned_docs/version-3.9.1/Serving_the_Internet/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Serving the Internet", + "position": 6 +} diff --git a/versioned_docs/version-3.9.1/Write_your_study/Adapt-pre-written-code-to-run-it-in-JATOS.md b/versioned_docs/version-3.9.1/Write_your_study/Adapt-pre-written-code-to-run-it-in-JATOS.md new file mode 100644 index 0000000000..f71bf238a5 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/Adapt-pre-written-code-to-run-it-in-JATOS.md @@ -0,0 +1,112 @@ +--- +title: Adapt pre written code to run it in JATOS +slug: /Adapt-pre-written-code-to-run-it-in-JATOS.html +sidebar_position: 3 +--- + + +**Make your existing code run in JATOS - or how to jatosify a study** + +You might have a task, experiment, survey, or study running in a browser. You might have all its files like HTML, JavaScripts, images, etc. And now you want to run it with JATOS? Then follow this page. + +**Development of a JATOS study usually happens on your local JATOS: [Run an experiment with JATOS - Workflow](Run-an-experiment-with-JATOS-Workflow.html)** + +### Create the study in your local JATOS + +1. Create a new study: click **Studies** in JATOS header -> click "**+**" -> click **New Study**. Choose a study title and click **Add**. JATOS will have created a new folder within your assets root folder (default is the study's UUID and the location in `/path_to_your_JATOS/study_assets_root/`). +1. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder. +1. Back in the JATOS GUI, and within the newly created study, create a new component by clicking **New Component**. Choose a title and set the HTML file name, to the name of the HTML file you just copied into the study folder. +1. In your HTML, CSS and JavaScripts, for your paths you can choose between 1) relative paths or 2) absolute paths. **Relative paths are recommended** since they are shorter and do not change after an export-import of a study. + + 1. **Relative paths)** Just use the relative path within your study's folder. + + E.g. if a file named 'survey.js' is in the root of the study's assets folder + + ```html + + ``` + + E.g. or if the file is in a subfolder 'lib' + + ```html + + ``` + + 1. **Absolute paths (deprecated))** Always use the prefix `/study_assets/` and then the study assets name you specified in your study's properties when you created it. + + E.g. if you want to load the file 'survey.js' and the study's assets folder is 'my-exp' + + ```html + + ``` + + ✰ For absolute paths make sure you understand the difference between the `study_assets_root` folder and the placeholder `study_assets` in your path names. `study_assets_root` is the folder in your system (or in the server) where the assets (HTML, JS, CSS, images, etc) of **all** your JATOS studies will be stored. You can [configure](JATOS_Configuration.html#study-assets-root-path) the location of this folder. `study_assets`, on the other hand, is just a placeholder that will go in your HTML files. JATOS will interpret this and replace the placeholder with the path, (specific to the study) that you entered in the field 'Study assets directory name' in your Study's Properties. The advantage of this is that you can change the location or name of the assets for any study, or export-import a study into a different computer, and the study will still run without having to make any changes in the HTML code. + +1. Now it's time for a first glimpse: Click the '**Run**' button in either the study's or the component's toolbar. Your experiment should run like it did before without JATOS. Use the browser's developer tools to check for eventually missing files and other occurring errors. + +### Edit your HTML and JavaScript + +Up to this point JATOS served as a mere provider of your files. Now we want to use a feature of JATOS: We want to store your result data in JATOS' safe database. + +1. Include the **_jatos.js_** library in your HTML. In your `` add the line + + ```html + ` + ``` + +1. Add **`jatos.onLoad`** + + Most studies with JATOS start with this call. So whatever you want to do in your study it should start there. + + ~~~javascript + jatos.onLoad(function() { + // start your code here + }); + ~~~ + +1. Now to actually **send your result data** to JATOS we use _jatos.js_' function [`jatos.submitResultData`](jatos.js-Reference.html#jatossubmitresultdata). We can pass this function any data in text format including JSON, CSV or XML. If you pass a JavaScript object it will be turned into JSON (stringified). + + E.g. if we want to send a JavaScript object as JSON + + ~~~javascript + jatos.submitResultData(myResultDataObject); + ~~~ + + `jatos.submitResultData` puts the data into JATOS database - old data that were submitted before will be overwritten. If you don't want to overwrite data you should rather use [`jatos.appendResultData`](jatos.js-Reference.html#jatosappendresultdata). + +1. Instead of submitting text you can also upload files with [`jatos.uploadResultFile`](jatos.js-Reference.html#jatosuploadresultfile). + +1. At the end of your component you will want to jump to another component or end the study. + + To jump to the next component: + + ~~~javascript + jatos.startNextComponent(); + ~~~ + + Or to just finish the study: + + ~~~javascript + jatos.endStudy(); + ~~~ + + You can combine this with sending result data: + + ~~~javascript + jatos.startNextComponent(myResultDataObject); + ~~~ + + or + + ~~~javascript + jatos.endStudy(myResultDataObject); + ~~~ + +That's about it. Infos about other _jatos.js_ functions and variables you can find in the [reference](jatos.js-Reference.html). + + +### Beyond the basics + +* Think about dividing your study into **several components**. You could have separate components e.g. for introduction, training, experiment and feedback. You could even consider splitting the experiment into several parts. One advantage is that if your participant stops in the middle of your study you still have the result data of the first components. Also, you can re-use components in different studies. +* Use the **study input** or **component input**, defined in the study or component properties. With them you can change variables of your code directly through JATOS' GUI, which might come handy if someone isn't good in JavaScript. +* You can add a **quit button** to your study to allow the participant to [abort at any time](Data-Privacy-and-Ethics.html#things-you-should-consider-in-your-studies). diff --git a/versioned_docs/version-3.9.1/Write_your_study/Change-studys-members.md b/versioned_docs/version-3.9.1/Write_your_study/Change-studys-members.md new file mode 100644 index 0000000000..a73bf09835 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/Change-studys-members.md @@ -0,0 +1,22 @@ +--- +title: Change study's members +slug: /Change-studys-members.html +sidebar_position: 7 +--- + +Each experimenter with access to the JATOS server (though the GUI) is a JATOS User. Users can create, modify and delete the studies they are members of. They can also export and delete results. + +A study in JATOS is allowed to have more than one users, also called members. Each member has the same rights, e.g. can run the study, create new Workers, add/change/delete components, export/delete results. Especially each member can add new members or remove existing members. + +Each study has a **Change users** button in its study toolbar. + +![Change study's members button](/img/v39x/change_studys_members_button.png) + +In this menu you can add single users by their username. Of course this works only if this is already a JATOS user. For privacy reasons JATOS never shows the username (which is often an email address) in the member list. + +A single user is removed by unchecking the checkbox in front of its name. + +Additionally it is possible, if your admins allow it, to add all JATOS users at once or remove all members at once. Then you will see the **Add All** and **Remove All** buttons. + +![Change study's members](/img/v39x/change_studys_members.png) + diff --git a/versioned_docs/version-3.9.1/Write_your_study/Combine_two_pre_written_studies_into_one.md b/versioned_docs/version-3.9.1/Write_your_study/Combine_two_pre_written_studies_into_one.md new file mode 100644 index 0000000000..850fc70803 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/Combine_two_pre_written_studies_into_one.md @@ -0,0 +1,61 @@ +--- +title: Combine two pre-written studies into one +slug: /Combine-two-pre-written-studies-into-one.html +sidebar_position: 3 +--- + + +**Take two separate studies and combine them into a single one** + +You might have created two parts of a study using different tools. For example, you coded a survey with [labjs](/labjs-and-JATOS.html) and a perceptual experiment with [OSWeb](OSWeb-and-JATOS.html). You have two _.jzip_ files from each of these tools, but now you want to combine them into one. Here's how. + +Note that this description works for any two halves of a study, coded in whatever way. (But of course, if you were the one writing the scripts instead of using an experiment builder, you'll likely not need this explanation). + + +### Ingredients + +To combine two studies into one you'll need: +1. A [**local instance**](Installation.html#easy-installation-on-your-local-computer) of JATOS. Make sure this is not the one on the server, but the one you run on your own computer. This will give you easy access to move and rename your files. +1. Information about where your study assets are: Go to [http://localhost:9000/jatos](http://localhost:9000/jatos). On the homepage, find the section "Where are my files". (It's big, you can't miss it). Find that folder on your computer. +1. The _.jzip_ for the first half of your study. +1. The _.jzip_ for the second half of your study. + +Note for 3. and 4.: You should not try to generate a _.jzip_ file by hand at this point (although it is possible). A [JZIP study archive](JATOS-Study-Archive-JZIP.html) file is a ZIP archive with a standardized content. They contain information that JATOS needs to understand that something is a study. + + +### Strategy + +The idea will be to, first, import one of these halves of a study into your local JATOS instance. Then, add the files from the second half as an additional component to the first half. + + +### Steps + +These steps sound complicated, but it's all really simple clicking around and copy-pasting. Basically a JATOS-study-collage. + +Imagine you have _half-study-1.jzip_ (a survey) and _half-study-2.jzip_ (a perceptual task). + +1. Import the _half-study-1.jzip_ into JATOS. You should get one study with a single component. +2. Identify the folder in your local computer where these study assets are. (Ingredient 2, described above.) +3. Import the _half-study-2.jzip_ into JATOS. You should get one study with a single component. +4. Look into the folder you found in Step 2. Navigate to the subfolder that corresponds to _half-study-2_. You should find a single _.html_ file (this is what actually displays your study) and probably a lot of other assets, including libraries and CSS stylesheets. +5. In your local JATOS: Go to the component properties of each of your study halves. Find the field with the path to the HTML file that runs your study. If the name of the HTML files is the same for both halves (it often is _index.html_), change the names. Now they are called _index-half-1.html_ and _index-half-2.html_. You can change the names in the component properties. JATOS will change the actual file name on your filesystem for you. (Confirm that you want this when prompted). +6. In your local filesystem: Copy all of the contents of this subfolder for _half-study-2_ into the subfolder for _half-study-1_. You now combined the information from both studies into a single folder and made sure that the HTML files are uniquely named. +7. In your local JATOS: Go to the your _half-study-1_. Click on "New component". In the properties of this new component, indicate the path to the HTML file from _half-study-2_. Copy any other properties that might exist (e.g. JSON input) from the single component in _half-study-2_ to this new component in _half-study-1_. +8. Now you have a complete, combined study. +9. Export this study from your local instance. +10. Import the _.jzip_ you created in step 9 into your online JATOS server. + + +### Troubleshooting + +Make sure that the study doesn't finish after the first component. In the javascript of the first component you should see something like: + + ~~~javascript + jatos.startNextComponent(myResultDataObject); + ~~~ + +and not + + ~~~javascript + jatos.endStudy(myResultDataObject); + ~~~ diff --git a/versioned_docs/version-3.9.1/Write_your_study/Create-a-new-study.md b/versioned_docs/version-3.9.1/Write_your_study/Create-a-new-study.md new file mode 100644 index 0000000000..6656139223 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/Create-a-new-study.md @@ -0,0 +1,33 @@ +--- +title: Create a new study +slug: /Create-a-new-study.html +sidebar_position: 1 +--- + +There are different ways to create a new study for JATOS: use a builder, with jsPsych, from scratch or by modifying an existing study. Then afterwards continue with [Write your own Study - Basics and Beyond](Write-your-own-Study-Basics-and-Beyond.html) or [Adapt Pre written Code to run it in JATOS](Adapt-pre-written-code-to-run-it-in-JATOS.html). + +**Developement of a JATOS study usually happens on your local JATOS: [Run an experiment with JATOS - Workflow](Run-an-experiment-with-JATOS-Workflow.html)** + + +### Use a builder - OpenSesame/OSWeb and lab.js + +Experiment builders like [OpenSesame/OSWeb](OSWeb-and-JATOS.html) and [lab.js](labjs-and-JATOS.html) have a point-and-click UI. They are easy to use and you don't have to care for the programming part. But they come with the limitation that they only allow you to do what is possible in the UI. If you want more freedom consider jsPsych or write your own study. + + +### Use jsPsych + +[jsPsych](http://www.jspsych.org/) is a popular library for running behavioral experiments in a web browser. We have an own web page describing using [jsPsych with JATOS](jsPsych-and-JATOS.html). + + +### Write your own study from scratch + +Writing your own study gives your the most freedom since it allows you to do whatever is possible in a modern browser. But you will have to program your own code in JavaScript, HTML and CSS. + +Go to the study sidebar by clicking on **Studies** in the header, top-left, then click on "**+**" and select **New Study**. Now an dialog opens where you can enter a title for the study and finally **Add** it. Next the study's page will open. Here you can edit its properties or add new components. All source code for your study has to got into the **study assets** folder. You can change the folder name in the study properties, but it is usually not necessary. The study assets folder is usually located in your JATOS installation folder. + + +### Modify an existing study + +Take an existing study (e.g. from [Example Studies](/Example-Studies)) as a prototype and modify it bit by bit. Go to the study sidebar by clicking on **Studies** in the header, top-left, then click on "**+**" and select **Import Study**. Then modify the source code in your **study assets** folder, which is usually in your JATOS installation folder. + + diff --git a/versioned_docs/version-3.9.1/Write_your_study/OSWeb-and-JATOS.md b/versioned_docs/version-3.9.1/Write_your_study/OSWeb-and-JATOS.md new file mode 100644 index 0000000000..d025198205 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/OSWeb-and-JATOS.md @@ -0,0 +1,22 @@ +--- +title: OSWeb/OpenSesame and JATOS +slug: /OSWeb-and-JATOS.html +hide_table_of_contents: true +sidebar_position: 6 +--- + +
+ +![](/img/OSweb_logo.png) + +
+ +OSWeb lets you run an [OpenSesame](https://osdoc.cogsci.nl) experiment on a browser. OpenSesame is a pretty neat program to create experiments for psychology, neuroscience, and experimental economics. You can get very far with drag-and-drop, and there's the chance to add code snippets if you need more flexibility. + +[OSWeb's documentation](https://osdoc.cogsci.nl/manual/osweb/workflow/) is far better than ours could ever be. So, here, we just point out that combining OSWeb with JATOS is pretty easy and straightforward: just export the experiment in OSWeb and import it in JATOS. + +If you want to use [Prolific](https://www.prolific.co/) to recruit participants for your OSWeb experiment running in JATOS then you can put the return link in the 'End Redirect URL' field of your Study Properties (in JATOS GUI). + +If you'd like to know more +* Sebastiaan Mathot's [tutorial](https://www.youtube.com/watch?v=0448NeoUaqU) +* [Workshop about OpenSesame, Python, and JATOS](https://www.youtube.com/playlist?list=PLSadj_kFpja_IOBQZrKf56RpjzUl3W6SP) (12 lessons) diff --git a/versioned_docs/version-3.9.1/Write_your_study/Session-Data-Three-Types.md b/versioned_docs/version-3.9.1/Write_your_study/Session-Data-Three-Types.md new file mode 100644 index 0000000000..84f0202977 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/Session-Data-Three-Types.md @@ -0,0 +1,58 @@ +--- +title: Session Data - Three Types +slug: /Session-Data-Three-Types.html +sidebar_position: 9 +--- + +### When to use the sessions? + +
+ +![](/img/three_session_types.png) + +
+ +Often you want to store information during a study run and share it with other components of the same study, or between workers of a group or batch. The three different session types let you transfer data in this way (shown by the curved arrows in the picture on the right). Workers can write into the sessions through _jatos.js_. + +The data stored in the sessions are **volatile** - do not use the sessions to store data permanently. Instead, store any information that might be useful for data analysis in the **Result Data**. Unlike the data stored in the sessions, the Result Data are stored permanently in the JATOS server, and will never be deleted automatically. + +The data stored in the sessions are not exported or imported together with a study. If you want data to be exported with a study, use the **study input** or **component input** defined in your study properties or component properties instead. + +
+ + +### Comparative Overview + +| | Batch Session | Group Session | Study Session | +|-|-------------------|-------------------|-------------------| +| **Scope (accesible by)** | All workers in a batch | All workers in a group | All components in a study | +| **Usage** | Exchange and store data relevant for all members of a batch | Exchange and temporarily store data relevant for all members of a group | Exchange and temporarily store data between components of a single study run | +| **Example use** | (Pseudo-)randomly assign conditions to different workers; Combine results from different groups working in the same batch | Store choices of the two members of a Prisoner's Dilemma game | Pass on correct answers between components; Keep track of the number of iterations of a given component that is repeated | +| **Lifetime** | Survives after all workers finished their studies | Automatically deleted once the group is finished | Deleted once the worker finished the study - Hence temporary| +| **Updated when and via** | Any time you call one of the [`jatos.batchSession` functions](/jatos.js-Reference.html#batch-session-functions) | Any time you call one of the [`jatos.groupSession` functions](/jatos.js-Reference.html#group-session-functions) | At the end of each component or if you call [`jatos.setStudySessionData`](jatos.js-Reference.html#jatossetstudysessiondata) | +| **Visible and editable from JATOS' GUI** | ![yes](/img/ok-24.ico) | ![yes](/img/ok-24.ico) | ![no](/img/x-24.ico) | +| **Requires WebSockets** | ![yes](/img/ok-24.ico) | ![yes](/img/ok-24.ico) | ![no](/img/x-24.ico) | +| **Included in exported studies** | ![no](/img/x-24.ico) | ![no](/img/x-24.ico) | ![no](/img/x-24.ico) | + + +### Example Study + +We have an [example study](/Example-Studies), where we show the three different session types in action. Try it yourself: + +1. Download and import the study. You'll find that the study contains two components: "First" and "Second". + +1. Run the study once: easiest is as a JATOS worker (just click 'Run' on the study bar, not on any of the component bars). + +1. The first component will prompt you for a name. It will then write the name you enter here into the **Study Session**. Because all components have access to the Study Session, the second component can read it and use your name in a chat window. + + ![First component screenshot](/img/ChatExample_1.png) + +1. When you click on 'Next', the second component will load. Here you will see two chat windows: The left one is called the group chat because it uses the Group Session; the right one is called batch chat because it uses the Batch Session. For now you're alone in these chat rooms. So, without closing this run and from new browser tabs, **run the study 2 more times (at least)**. You can choose any study link type you want. + + ![Second component screenshot](/img/ChatExample_2.png) + +1. Now you have 3 simultaneous study runs. You will notice while writing into the group chat that two of your workers are in the same group - the third one has their own group. Why 2 per group? Because we [set the groups to a maximum of 2 members each](Write-Group-Studies-I-Setup.html#group-settings-in-each-batchs-properties). The group chat will use the **Group Session** to allow the 2 members of each group to communicate with each other. Members of other groups will not have access to the chats of this group. However, anything written into the **Batch Session** will be accesssible by all workers that are members of this batch, regardless of the group they're in. + + ![Second component screenshot](/img/ChatExample_3.png) + ![Second component screenshot](/img/ChatExample_4.png) + diff --git a/versioned_docs/version-3.9.1/Write_your_study/Submit-and-upload-data-to-the-server.md b/versioned_docs/version-3.9.1/Write_your_study/Submit-and-upload-data-to-the-server.md new file mode 100644 index 0000000000..3e803790c0 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/Submit-and-upload-data-to-the-server.md @@ -0,0 +1,26 @@ +--- +title: Submit and upload data to the server +slug: /Submit-and-upload-data-to-the-server.html +sidebar_position: 8 +--- + +If you wrote your study with HTML/JavaScript/CSS, you'll need to know how to send to the JATOS server for safe storage and easy later retrieval. Here we describe how to submit data. See [Manage Results](Manage-Results.html) to know how to retrieve it. + + +### Submit result data + +There are a couple of _jatos.js_ functions that allow you to send data to the JATOS server. The result data can be anything that can be put into text, which includes formats like JSON or CSV. Images, audio or video data can only be sent via Upload (explained below). + +The two functions [`jatos.submitResultData`](jatos.js-Reference.html#jatossubmitresultdata) and [`jatos.appendResultData`](jatos.js-Reference.html#jatosappendresultdata) let you submit text data to the server. They are similar to each other. The only difference is that the first overwrites the data and therefore deletes previously sent data, while the latter appends new data to old data. + +Then there are a couple of functions that do something else (primarily) but allow you to send result data out of convenience, since they usually go together anyway. These are all functions that start a new component (e.g. [`jatos.startNextComponent`](jatos.js-Reference.html#jatosstartnextcomponent), [`jatos.startComponentByPos`](jatos.js-Reference.html#jatosstartcomponentbypos)) and all functions that end a study ([`jatos.endStudy`](jatos.js-Reference.html#jatosendstudy) and [`jatos.endStudyAndRedirect`](jatos.js-Reference.html#jatosendstudyandredirect)). + +Sending data to a server can take some time, depending on the internet connection and the size of the result data. The convenience functions have the advantage that they will execute their primary function (e.g. start next component) only *after* the result data have been submitted. Therefore these are generally safer ways to submit your result data. + +### Upload and download result files + +If you want to upload audio, video, images or any other data that is not in text format, then uploading a result file is what you need: [`jatos.uploadResultFile`](jatos.js-Reference.html#jatosuploadresultfile). + +And if you want to, in a later component, access the uploaded files again you can download them with [`jatos.downloadResultFile`](jatos.js-Reference.html#jatosdownloadresultfile). + +For more real-world examples have a look at the ['Drawing' and the 'Video Recording' examples](/Example-Studies). diff --git a/versioned_docs/version-3.9.1/Write_your_study/Write-your-own-Study-Basics-and-Beyond.md b/versioned_docs/version-3.9.1/Write_your_study/Write-your-own-Study-Basics-and-Beyond.md new file mode 100644 index 0000000000..fcb2912403 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/Write-your-own-Study-Basics-and-Beyond.md @@ -0,0 +1,118 @@ +--- +title: Write your own Study - Basics and Beyond +slug: /Write-your-own-Study-Basics-and-Beyond.html +sidebar_position: 2 +--- + +After you [created a new study](Create-a-new-study.html) ... what comes next? + +**Developement of a JATOS study usually happens on your local JATOS: [Run an experiment with JATOS - Workflow](Run-an-experiment-with-JATOS-Workflow.html)** + + +## Add a component + +If you have an empty study you want to add a component. A component corresponds to a webpage defined by an HTML file. A study can have more than one component - this is actually a strength of JATOS: e.g. one can combine different experiments into one, or easily add an survey to an existing experiment. + +To add a component go to your study page and click on **New Component**. + +![New Component](/img/v39x/new-component.png) + +Then in the following form you define the component's 'Title' and most importantly its 'HTML file path' (This is the path to the HTML file that starts this component). + +![New Component](/img/v39x/new-component-properites.png) + +Click on **Add** and you are done. You can change the component's properties by clicking on 'Properties' in the component's row. If you add more than one component you can change the order in which they run by drag-and-drop on the position button. + +![Position Component](/img/v39x/component-position-dragndrop.png) + + +## Study assets + +All your files (e.g. HTML, CSS, JavaScript and media files) go into your study assets directory. That includes all component's HTML files. You can find the study assets directory in a directory called `study_assets_root` in your JATOS installation directory. You can change the study assets directory's name in the study properties, but it's usually not necessary. + +![Position Component](/img/v39x/study-assets-name.png) + + +## Mandatory lines in your components' HTML + +A study can have one or multiple components and each component has an HTML file associated that is defined in the component's properties. + +Here is the absolute minimum that any component HTML file must have to run with JATOS: + +1. A link to the _jatos.js_ library in the head section + + ~~~ html + + + + + + ~~~ + +1. The second bit is not really necessary but without defining the `jatos.onLoad` callback function you won't be able to use most of _jatos.js_' features. Of course you could start right away with any JavaScript but if you want to use _jatos.js_' variables and functions you have to wait until _jatos.js_ is finished initializing. + + ~~~ html + + ~~~ + + +## Save your result data + +You probably want to save the data that is collected during your experiments. There are generally two ways to do this: 1) result data or 2) result files - and there is a [documentation page about it](Submit-and-upload-data-to-the-server.html). + + +## _jatos.js_ Reference + +In your JavaScript you will use _jatos.js_ to handle everything JATOS related and in its [reference](jatos.js-Reference.html) every function and field is described in detail. + + +## Study input and component input + +Your experiment is defined by its source code, its HTML, JavaScript and CSS. There you specify all text or parameters. But sometimes you want to be able to quickly change your experiment without touching the source code. + +E.g. you want to be able to quickly change +* an introductory text +* the number of trials +* some parameter needed in the experiment + +This you can achieve with the "Study input" or "Component input" (in older JATOS versions they are called "Study JSON Input" and "Component JSON Input") because both can be easily edited in the study properties or component properties. + +![Study properties / study input](/img/v39x/study-input.png) + +Both input fields take [JSON](https://www.w3schools.com/whatis/whatis_json.asp) and the data you put in there is then available in your study's JavaScript via `jatos.studyJsonInput` and `jatos.componentJsonInput`. + +The difference between the study input and component input is that the first one is available during the whole study run, in all components, and the latter one only in the component for which it is specified. + +**Example:** + +If you put the following in the study input + +```json +{ + "numberOfTrials": 12, + "retries": 5, + "order": [ + 4, + 3, + 0, + 1 + ] +} +``` + +you can access those fields in your JavaScript with `jatos.studyJsonInput.numberOfTrials`, `jatos.studyJsonInput.retries` and `jatos.studyJsonInput.order`. + + +## Study / batch / group session + +The sessions are there to help you exchange data within a study, batch or group. The study session allows to pass on data within the same study run, from one component to the next. With the batch session one can transfer data between study runs that belong to the same batch. There is a whole page dedicated to those sessions: [Session Data - Three Types](/Session-Data-Three-Types.html). + + +## Group studies + +JATOS allows group studies in which several participants can work together on the same experiment and exchange data in real-time. +To get an idea it's best to start with [examples](Example-Group-Studies.html), then one can go on to write them: [Write Group Studies I - Setup](Write-Group-Studies-I-Setup.html) and [Write Group Studies II - JavaScript and Messaging](Write-Group-Studies-II-JavaScript-and-Messaging.html). diff --git a/versioned_docs/version-3.9.1/Write_your_study/_category_.json b/versioned_docs/version-3.9.1/Write_your_study/_category_.json new file mode 100644 index 0000000000..78484f0cb4 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Write your study", + "position": 2 +} diff --git a/versioned_docs/version-3.9.1/Write_your_study/jsPsych-and-JATOS.md b/versioned_docs/version-3.9.1/Write_your_study/jsPsych-and-JATOS.md new file mode 100644 index 0000000000..dc1eb32582 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/jsPsych-and-JATOS.md @@ -0,0 +1,47 @@ +--- +title: jsPsych and JATOS +slug: /jsPsych-and-JATOS.html +hide_table_of_contents: true +sidebar_position: 4 +--- + +
+ +![](/img/jspsych-logo.png) + +
+ +JATOS basically cares for the server side: it stores result data, does worker management etc. JATOS doesn't care so much for what happens in the browser itself - your HTML, JavaScript and CSS. Of course you can write this all yourself, but you could also use a framework for this. A very good one is [jsPsych](http://www.jspsych.org/). + +In [our example studies](/Example-Studies) are a couple of jsPsych ones. + +Here are the necessary changes if you want to adapt your jsPsych experiment so that it runs within (and sends the result data to) JATOS. Additionally you can have a look at [Adapt Pre written Code to run it in JATOS](Adapt-pre-written-code-to-run-it-in-JATOS.html). + +Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look [here](/3.6.x/jsPsych-and-JATOS.html)). + +### How to turn your jsPsych 7 experiment into a JATOS study + +1. Include the _jatos.js_ library in the `` of your HTML + + ~~~ html + + ~~~ + +1. Tell jsPsych to send your result data to JATOS. If you want add a 'Cancel' button with `jatos.addAbortButton`, add the line included below (omit if you don't want the automatic abort button). + + ~~~ javascript + var jsPsych = initJsPsych({ + on_trial_start: jatos.addAbortButton, + on_finish: () => jatos.endStudy(jsPsych.data.get().json()) + }); + ~~~ + +1. Wrap jsPsych's run in `jatos.onLoad`. + + ~~~ javascript + jatos.onLoad(() => { + jsPsych.run(timeline); + }); + ~~~ + +That's all. Have a look at the 'Simple Reaction Time Task' in our [example studies](/Example-Studies) to see a full example with jsPsych 7. diff --git a/versioned_docs/version-3.9.1/Write_your_study/labjs-and-JATOS.md b/versioned_docs/version-3.9.1/Write_your_study/labjs-and-JATOS.md new file mode 100644 index 0000000000..6b2131ff76 --- /dev/null +++ b/versioned_docs/version-3.9.1/Write_your_study/labjs-and-JATOS.md @@ -0,0 +1,20 @@ +--- +title: lab.js and JATOS +slug: /labjs-and-JATOS.html +hide_table_of_contents: true +sidebar_position: 5 +--- + +
+ +![](/img/labjs_logo.png) + +
+ +[lab.js](https://lab.js.org/) is an easy to use tool to create online experiments. Their [builder](https://labjs.felixhenninger.com/) makes creating an online experiment a piece of cake - although you can also write code yourself: lab.js supports this too. + +lab.js and JATOS fit perfectly together: **lab.js directly exports JATOS studies**. So you don't need to write or modify any bits of code. You can create your experiment with lab.js. Then just import your studies into JATOS and let particpants run it. + +lab.js already has a [great documentation](https://labjs.readthedocs.io/en/latest/index.html) and one page there is solely dedicated to JATOS: [Collecting data with JATOS](https://labjs.readthedocs.io/en/latest/learn/deploy/3c-jatos.html). + +That's all there is to say. diff --git a/versioned_sidebars/version-3.9.1-sidebars.json b/versioned_sidebars/version-3.9.1-sidebars.json new file mode 100644 index 0000000000..caea0c03ba --- /dev/null +++ b/versioned_sidebars/version-3.9.1-sidebars.json @@ -0,0 +1,8 @@ +{ + "tutorialSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/versions.json b/versions.json index a27f4bbd71..cc13e2fe8d 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "3.9.1", "3.8.1", "3.7.1", "3.6.1"