diff --git a/3.6.x/Adapt-pre-written-code-to-run-it-in-JATOS.html b/3.6.x/Adapt-pre-written-code-to-run-it-in-JATOS.html index 3eebe4716..5b6f45232 100644 --- a/3.6.x/Adapt-pre-written-code-to-run-it-in-JATOS.html +++ b/3.6.x/Adapt-pre-written-code-to-run-it-in-JATOS.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Adapt pre written code to run it in JATOS

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. Maybe you wrote it with jsPsych or got it from The Experiment Factory. And now you want to run it with JATOS? Then follow this page.

Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

Create the study in your local JATOS​

  1. Create a new study with the 'New Study' button in JATOS' header. Choose a study title and a folder name. Leave the other fields empty for now and click 'Create'. JATOS will have created a new folder within your assets root folder (default is /path_to_your_JATOS/study_assets_root/).

  2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

  3. Back in the JATOS GUI, and within the newly created study, create a new component by clicking 'Components' and then 'New'. Choose a component title and set the HTML file name, to the name of the HTML file you just copied into the study folder.

  4. In your HTML, CSS and JavaScripts, for your paths you can choose between 1) relative paths or 2) absolute paths. Relative paths are usually shorter and easier to handle but are only available since JATOS version 3.2.3.

    1. Relative paths (since v3.2.3 and recommended way)) 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

      <script src="survey.js"></script>

      E.g. or if the file is in a subfolder 'lib'

      <script src="lib/survey.js"></script>

    2. Absolute paths) 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'

      <script src="/study_assets/my-exp/survey.js"></script>

      ✰ 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 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 <head>

    • JATOS < v3.3.1) Add the line 
    <script src="/assets/javascripts/jatos.js"></script>
    • JATOS >= v3.3.1) Add the line 
    <script src="jatos.js"></script>`

  2. Add jatos.onLoad

    Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

    jatos.onLoad(function() {
      // initialize and start your JavaScript here 
    });

    E.g. if you want to initialize a jsPsych experiment:

    jatos.onLoad(function() {
      jsPsych.init( {
        ...
      });
    });

  3. Now to actually send our result data to JATOS we use jatos.js' function jatos.submitResultData. We can pass this function any data in text format including JSON, CSV or XML.

    E.g. if we want to send a JavaScript object as JSON

    var resultJson = JSON.stringify(myObject);
    jatos.submitResultData(resultJson, jatos.startNextComponent);

    Conveniently but optionally jatos.submitResultData takes a second parameter which specifies what should be done after the result data got sent. Usually one want to jump to the next component (jatos.startNextComponent) or finish the study (jatos.endStudy).

    Another example where we use jsPsych: We have to put jatos.submitResultData into jsPsych's on_finish:

    jsPsych.init( {
      ...
      on_finish: function(data) {
        // Submit results to JATOS
        var resultJson = JSON.stringify(jsPsych.data.getData());
        jatos.submitResultData(resultJson, jatos.startNextComponent);
      }
    });

That's about it. Infos about other jatos.js functions and variables you can find in the reference.

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's and component's 'JSON input data'. 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.
- +
Skip to main content
Version: 3.6.x and earlier

Adapt pre written code to run it in JATOS

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. Maybe you wrote it with jsPsych or got it from The Experiment Factory. And now you want to run it with JATOS? Then follow this page.

Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

Create the study in your local JATOS​

  1. Create a new study with the 'New Study' button in JATOS' header. Choose a study title and a folder name. Leave the other fields empty for now and click 'Create'. JATOS will have created a new folder within your assets root folder (default is /path_to_your_JATOS/study_assets_root/).

  2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

  3. Back in the JATOS GUI, and within the newly created study, create a new component by clicking 'Components' and then 'New'. Choose a component title and set the HTML file name, to the name of the HTML file you just copied into the study folder.

  4. In your HTML, CSS and JavaScripts, for your paths you can choose between 1) relative paths or 2) absolute paths. Relative paths are usually shorter and easier to handle but are only available since JATOS version 3.2.3.

    1. Relative paths (since v3.2.3 and recommended way)) 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

      <script src="survey.js"></script>

      E.g. or if the file is in a subfolder 'lib'

      <script src="lib/survey.js"></script>

    2. Absolute paths) 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'

      <script src="/study_assets/my-exp/survey.js"></script>

      ✰ 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 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 <head>

    • JATOS < v3.3.1) Add the line 
    <script src="/assets/javascripts/jatos.js"></script>
    • JATOS >= v3.3.1) Add the line 
    <script src="jatos.js"></script>`

  2. Add jatos.onLoad

    Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

    jatos.onLoad(function() {
      // initialize and start your JavaScript here 
    });

    E.g. if you want to initialize a jsPsych experiment:

    jatos.onLoad(function() {
      jsPsych.init( {
        ...
      });
    });

  3. Now to actually send our result data to JATOS we use jatos.js' function jatos.submitResultData. We can pass this function any data in text format including JSON, CSV or XML.

    E.g. if we want to send a JavaScript object as JSON

    var resultJson = JSON.stringify(myObject);
    jatos.submitResultData(resultJson, jatos.startNextComponent);

    Conveniently but optionally jatos.submitResultData takes a second parameter which specifies what should be done after the result data got sent. Usually one want to jump to the next component (jatos.startNextComponent) or finish the study (jatos.endStudy).

    Another example where we use jsPsych: We have to put jatos.submitResultData into jsPsych's on_finish:

    jsPsych.init( {
      ...
      on_finish: function(data) {
        // Submit results to JATOS
        var resultJson = JSON.stringify(jsPsych.data.getData());
        jatos.submitResultData(resultJson, jatos.startNextComponent);
      }
    });

That's about it. Infos about other jatos.js functions and variables you can find in the reference.

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's and component's 'JSON input data'. 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.
+ \ No newline at end of file diff --git a/3.6.x/Administration.html b/3.6.x/Administration.html index 813effe59..7aeb6ed7f 100644 --- a/3.6.x/Administration.html +++ b/3.6.x/Administration.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Administration

Since JATOS v3.6.1 JATOS includes an Administration page. Here users with admin rights 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.

Administration screenshot

On the menu you will find links to two additional administration pages:

User Manager​

Manage users, passwords, and rights from here. Find more details on its documentation page

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.

For larger JATOS installation it can take up to a couple minutes to gather all data for this page

Studies Administration

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.
- +
Skip to main content
Version: 3.6.x and earlier

Administration

Since JATOS v3.6.1 JATOS includes an Administration page. Here users with admin rights 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.

Administration screenshot

On the menu you will find links to two additional administration pages:

User Manager​

Manage users, passwords, and rights from here. Find more details on its documentation page

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.

For larger JATOS installation it can take up to a couple minutes to gather all data for this page

Studies Administration

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.
+ \ No newline at end of file diff --git a/3.6.x/Bring-your-JATOS-online.html b/3.6.x/Bring-your-JATOS-online.html index dcffff575..f4fc6c35f 100644 --- a/3.6.x/Bring-your-JATOS-online.html +++ b/3.6.x/Bring-your-JATOS-online.html @@ -10,14 +10,14 @@ - +
Skip to main content
Version: 3.6.x and earlier

Bring your JATOS online

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 timeSetup difficultyCostNumber of JATOS user / JATOS workers
1. Expose your local JATOSfasteasynoneyou / few †
2. Cloud serverfast to mediumdepends on your vendoryesmany / many ‡
3. Own servermedium to slow (depends on your IT)needs admin skillsask your ITmany / many ‡

†) 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

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 or JATOS on AWS (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

- +‡) 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

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 or JATOS on AWS (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

+ \ No newline at end of file diff --git a/3.6.x/Change-studys-members.html b/3.6.x/Change-studys-members.html index 0217c136c..393590d9b 100644 --- a/3.6.x/Change-studys-members.html +++ b/3.6.x/Change-studys-members.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Change study's members

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&#39;s members button

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&#39;s members

- +
Skip to main content
Version: 3.6.x and earlier

Change study's members

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&#39;s members button

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&#39;s members

+ \ No newline at end of file diff --git a/3.6.x/Configure-JATOS-on-a-Server.html b/3.6.x/Configure-JATOS-on-a-Server.html index 32f83edc5..c399ca52e 100644 --- a/3.6.x/Configure-JATOS-on-a-Server.html +++ b/3.6.x/Configure-JATOS-on-a-Server.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Configure JATOS on a Server

Restart JATOS after making any changes to the configuration (loader.sh restart)

IP / domain and port​

By default JATOS binds to all locally available IP addresses including 127.0.0.1 on port 9000. If you don't want to use a proxy in front of JATOS, you have several ways to configure the host name or IP address and the port:

  1. Since JATOS 3.3.5 it is possible to set up IP and port via conf/production.conf: Edit play.server.http.address and play.server.http.port and restart JATOS. E.g. to run on IP 192.168.0.100 and port 80:

    play.server.http.address = "192.168.0.100"
    play.server.http.port = 80

  2. Via command-line arguments -Dhttp.address and -Dhttp.port, e.g. with the following command you'd start JATOS with IP 10.0.0.1 and port 80

    loader.sh start -Dhttp.address=10.0.0.1 -Dhttp.port=80

  3. (DEPRECATED) In loader.sh change the values of 'address' and 'port' according to your IP address or domain name and port. Restart JATOS after editing.

    address="172.16.0.1"
    port="8080"

URL base path (JATOS >= v3.3.1)​

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 JATOS' URL all start with "www.example.org/mybasepath/". This can be achieved in two ways:

  1. Via the command-line argument -DJATOS_URL_BASE_PATH, e.g.

    loader.sh start -DJATOS_URL_BASE_PATH="/mybasepath/"

  2. Via conf/production.conf: change play.http.context

    play.http.context = "/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.

Study assets root path​

By default the study assets root folder (where all your study's HTML, JavaScript files etc. are stored) is located within JATOS installation's folder in study_assets_root. There are three ways to change this path:

  1. Via the command-line argument -DJATOS_STUDY_ASSETS_ROOT_PATH, e.g.

    loader.sh start -DJATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

  2. Via conf/production.conf: change jatos.studyAssetsRootPath

    jatos.studyAssetsRootPath="/path/to/my/jatos_study_assets_root"

  3. Via the environment variable JATOS_STUDY_ASSETS_ROOT_PATH, e.g. the following export adds it to the env variables:

    export JATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

MySQL Database​

See JATOS with MySQL

JVM arguments​

All JVM arguments can be used with loader.sh but all arguments starting with -X need an extra suffix -J. E.g. -Xmx (to change JVM's max heap memory) has to be written as -J-Xmx.

loader.sh start -J-Xmx4G   # Allow max 4 GB (heap) memory

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 in the conf/production.conf with the following two properties.

  • jatos.user.password.length - Set with an positive integer (default is 7)
  • jatos.user.password.strength - Set to 0, 1, 2, or 3 (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 (#?!@$%^&*-)
    • 3: At least one uppercase Latin letter, one lowercase Latin letter, one number and one special character (#?!@$%^&*-)

Study result data (JATOS >= v3.5.9)​

You can change the allowed size of a component's result data. This can be used to reduce the load on the server, especially network and database. Sometimes its necessary to increase the value if certain studies have larger result data needs. The property for this in conf/production.conf is jatos.resultData.maxSize. By default it's set to 5 MB per component run.

E.g. to reduce the allowed size per component to 1 MB:

jatos.resultData.maxSize = 1MB

Uploading of study result files (JATOS >= v3.5.1)​

  1. Via conf/production.conf

    • jatos.resultUploads.enabled - Enables study result files uploads (default is true)
    • jatos.resultUploads.path - Path in the file system where the uploaded result files will be stored (default is './result_uploads')
    • jatos.resultUploads.maxFileSize - Max file size for one single uploaded result file (default is 30 MB)
    • jatos.resultUploads.limitPerStudyRun - Limit of all uploaded result files of one single study run (default is 50MB)

  2. Via environment variables (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE only since 3.5.6)

    export JATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder"
    export JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB
    export JATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

  3. Via command-line arguments (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE only since 3.5.6)

    loader.sh start -DJATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder" -DJATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB -DJATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

Study logs (since JATOS >= 3.2.1)​

  1. Via conf/production.conf

    • jatos.studyLogs.enabled - (since JATOS >= 3.5.1) - Enables Study Logs (default is true)
    • jatos.studyLogs.path - (since JATOS >= 3.2.1) - Path in the file system where the Study Logs will be stored (default is './study_logs')

  2. The path can be configured via environment variables

    export JATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

  3. The path can be configured via command-line arguments

    loader.sh start -DJATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

LDAP authentication (since JATOS >= 3.5.4)​

By default JATOS uses only locally stored users and no LDAP. LDAP configuration is only possible in conf/production.conf. At the moment LDAP users still have to be created manually in JATOS' User manager (with the checkbox LDAP turned on).- only authentication is done via LDAP.

  • jatos.user.authentication.ldap.url - Specifies URL of the LDAP server. Not set or an empty string means no authentication via LDAP.
  • jatos.user.authentication.ldap.basedn - LDAP base domain name (e.g. "dc=example,dc=com"). Not set or an empty string means no authentication via LDAP.
  • jatos.user.authentication.ldap.timeout - Time in milliseconds JATOS waits for a response from your LDAP server. Default is 5000 ms.

If your LDAP uses encryption, you have to add your certificate to JATOS' trusted certificates defined with play.ws.ssl.trustManager.stores. 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.

User session configuration​

The user session is part of JATOS secuity measurments (more about security) and can be configured in conf/production.conf.

  • jatos.userSession.validation - (since JATOS >= 3.1.10) - toggles user session validation. If turned on (true) only the IP which was used at login time is allowed to be used for subsequent requests by this user. This helps preventing session hijacking and adds an addional layer of security. But on the downside it also prevents using the same user in JATOS from different browsers at the same time. By default it is set to false to allow an easy use of a local JATOS. On a server installation it should be set to true, although sometimes this not possible, e.g. if your users have an often changing, dynamic IP address. WARNING: Turning off the user session validation reduces JATOS security!

Other configs are:

  • jatos.userSession.timeout - time in minutes a user stays logged in (default is 1440 = 1 day)
  • jatos.userSession.inactivity - defines the time in minutes a user is automatically logged out after inactivity (default is 60)

Customize JATOS' home page​

More here.

Other configuration in production.conf​

Some other properties can be configured in the conf/production.conf.

  • play.http.session.secure - secure session cookie: set true to restrict user access to HTTPS (default is false)
  • jatos.idCookies.secure - secure ID cookies: set true to restrict worker access to HTTPS (default is false)
  • jatos.idCookies.sameSite - defines the ID cookies' 'SameSite' attribute: allowed values are None, Lax, or Strict. Default is None.
  • jatos.studyMembers.allowAddAllUsers - Allow to add all users that exist on a JATOS to be added at once as members of a study. Default is true.
  • jatos.resultData.export.useTmpFile - If true, result data that are fetched from the database are first stored in a temporary file and only when they are all gathered the file is sent to the browser. If false the result data are streamed directly from the database to the browser. Default is false.
  • jatos.maxResultsDbQuerySize - Maximal number of results to be fetched from the DB at once (default is 10)

Apart from those all configuration properties possible in the Play Framework are possible in JATOS' production.conf too, e.g.

  • play.pidfile.path - Path to the file that contains the process id of the started JATOS application (default is ./RUNNING_PID)
- +
Skip to main content
Version: 3.6.x and earlier

Configure JATOS on a Server

Restart JATOS after making any changes to the configuration (loader.sh restart)

IP / domain and port​

By default JATOS binds to all locally available IP addresses including 127.0.0.1 on port 9000. If you don't want to use a proxy in front of JATOS, you have several ways to configure the host name or IP address and the port:

  1. Since JATOS 3.3.5 it is possible to set up IP and port via conf/production.conf: Edit play.server.http.address and play.server.http.port and restart JATOS. E.g. to run on IP 192.168.0.100 and port 80:

    play.server.http.address = "192.168.0.100"
    play.server.http.port = 80

  2. Via command-line arguments -Dhttp.address and -Dhttp.port, e.g. with the following command you'd start JATOS with IP 10.0.0.1 and port 80

    loader.sh start -Dhttp.address=10.0.0.1 -Dhttp.port=80

  3. (DEPRECATED) In loader.sh change the values of 'address' and 'port' according to your IP address or domain name and port. Restart JATOS after editing.

    address="172.16.0.1"
    port="8080"

URL base path (JATOS >= v3.3.1)​

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 JATOS' URL all start with "www.example.org/mybasepath/". This can be achieved in two ways:

  1. Via the command-line argument -DJATOS_URL_BASE_PATH, e.g.

    loader.sh start -DJATOS_URL_BASE_PATH="/mybasepath/"

  2. Via conf/production.conf: change play.http.context

    play.http.context = "/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.

Study assets root path​

By default the study assets root folder (where all your study's HTML, JavaScript files etc. are stored) is located within JATOS installation's folder in study_assets_root. There are three ways to change this path:

  1. Via the command-line argument -DJATOS_STUDY_ASSETS_ROOT_PATH, e.g.

    loader.sh start -DJATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

  2. Via conf/production.conf: change jatos.studyAssetsRootPath

    jatos.studyAssetsRootPath="/path/to/my/jatos_study_assets_root"

  3. Via the environment variable JATOS_STUDY_ASSETS_ROOT_PATH, e.g. the following export adds it to the env variables:

    export JATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

MySQL Database​

See JATOS with MySQL

JVM arguments​

All JVM arguments can be used with loader.sh but all arguments starting with -X need an extra suffix -J. E.g. -Xmx (to change JVM's max heap memory) has to be written as -J-Xmx.

loader.sh start -J-Xmx4G   # Allow max 4 GB (heap) memory

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 in the conf/production.conf with the following two properties.

  • jatos.user.password.length - Set with an positive integer (default is 7)
  • jatos.user.password.strength - Set to 0, 1, 2, or 3 (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 (#?!@$%^&*-)
    • 3: At least one uppercase Latin letter, one lowercase Latin letter, one number and one special character (#?!@$%^&*-)

Study result data (JATOS >= v3.5.9)​

You can change the allowed size of a component's result data. This can be used to reduce the load on the server, especially network and database. Sometimes its necessary to increase the value if certain studies have larger result data needs. The property for this in conf/production.conf is jatos.resultData.maxSize. By default it's set to 5 MB per component run.

E.g. to reduce the allowed size per component to 1 MB:

jatos.resultData.maxSize = 1MB

Uploading of study result files (JATOS >= v3.5.1)​

  1. Via conf/production.conf

    • jatos.resultUploads.enabled - Enables study result files uploads (default is true)
    • jatos.resultUploads.path - Path in the file system where the uploaded result files will be stored (default is './result_uploads')
    • jatos.resultUploads.maxFileSize - Max file size for one single uploaded result file (default is 30 MB)
    • jatos.resultUploads.limitPerStudyRun - Limit of all uploaded result files of one single study run (default is 50MB)

  2. Via environment variables (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE only since 3.5.6)

    export JATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder"
    export JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB
    export JATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

  3. Via command-line arguments (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE only since 3.5.6)

    loader.sh start -DJATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder" -DJATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB -DJATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

Study logs (since JATOS >= 3.2.1)​

  1. Via conf/production.conf

    • jatos.studyLogs.enabled - (since JATOS >= 3.5.1) - Enables Study Logs (default is true)
    • jatos.studyLogs.path - (since JATOS >= 3.2.1) - Path in the file system where the Study Logs will be stored (default is './study_logs')

  2. The path can be configured via environment variables

    export JATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

  3. The path can be configured via command-line arguments

    loader.sh start -DJATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

LDAP authentication (since JATOS >= 3.5.4)​

By default JATOS uses only locally stored users and no LDAP. LDAP configuration is only possible in conf/production.conf. At the moment LDAP users still have to be created manually in JATOS' User manager (with the checkbox LDAP turned on).- only authentication is done via LDAP.

  • jatos.user.authentication.ldap.url - Specifies URL of the LDAP server. Not set or an empty string means no authentication via LDAP.
  • jatos.user.authentication.ldap.basedn - LDAP base domain name (e.g. "dc=example,dc=com"). Not set or an empty string means no authentication via LDAP.
  • jatos.user.authentication.ldap.timeout - Time in milliseconds JATOS waits for a response from your LDAP server. Default is 5000 ms.

If your LDAP uses encryption, you have to add your certificate to JATOS' trusted certificates defined with play.ws.ssl.trustManager.stores. 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.

User session configuration​

The user session is part of JATOS secuity measurments (more about security) and can be configured in conf/production.conf.

  • jatos.userSession.validation - (since JATOS >= 3.1.10) - toggles user session validation. If turned on (true) only the IP which was used at login time is allowed to be used for subsequent requests by this user. This helps preventing session hijacking and adds an addional layer of security. But on the downside it also prevents using the same user in JATOS from different browsers at the same time. By default it is set to false to allow an easy use of a local JATOS. On a server installation it should be set to true, although sometimes this not possible, e.g. if your users have an often changing, dynamic IP address. WARNING: Turning off the user session validation reduces JATOS security!

Other configs are:

  • jatos.userSession.timeout - time in minutes a user stays logged in (default is 1440 = 1 day)
  • jatos.userSession.inactivity - defines the time in minutes a user is automatically logged out after inactivity (default is 60)

Customize JATOS' home page​

More here.

Other configuration in production.conf​

Some other properties can be configured in the conf/production.conf.

  • play.http.session.secure - secure session cookie: set true to restrict user access to HTTPS (default is false)
  • jatos.idCookies.secure - secure ID cookies: set true to restrict worker access to HTTPS (default is false)
  • jatos.idCookies.sameSite - defines the ID cookies' 'SameSite' attribute: allowed values are None, Lax, or Strict. Default is None.
  • jatos.studyMembers.allowAddAllUsers - Allow to add all users that exist on a JATOS to be added at once as members of a study. Default is true.
  • jatos.resultData.export.useTmpFile - If true, result data that are fetched from the database are first stored in a temporary file and only when they are all gathered the file is sent to the browser. If false the result data are streamed directly from the database to the browser. Default is false.
  • jatos.maxResultsDbQuerySize - Maximal number of results to be fetched from the DB at once (default is 10)

Apart from those all configuration properties possible in the Play Framework are possible in JATOS' production.conf too, e.g.

  • play.pidfile.path - Path to the file that contains the process id of the started JATOS application (default is ./RUNNING_PID)
+ \ No newline at end of file diff --git a/3.6.x/Connect-to-Mechanical-Turk.html b/3.6.x/Connect-to-Mechanical-Turk.html index 0cc2e21c8..f2570cf5b 100644 --- a/3.6.x/Connect-to-Mechanical-Turk.html +++ b/3.6.x/Connect-to-Mechanical-Turk.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Use MTurk

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 before you let real workers do it.

You will need​

  • A requester Mturk account
  • Your study running on a JATOS server
  • A description of the study (this can be the same as the one you included in the study description within JATOS)

On JATOS page​

In JATOS, go to the Study Toolbar ⟶ Worker & Batch Manager

JATOS GUI screenshot

  1. Open the Worker Setup of the batch you want to run

  2. Enable the MTurk worker type

  3. 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

On MTurk's page​

You first have to create a project in the MTurk interface:

  1. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project

  2. Complete the Enter Properties tab

  3. Click on the Design layout button in the bottom of the page.

  4. 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

  5. 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).

  6. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

    MTurk Schreenshot

What should happen​

When an MTurk worker finishes a study they'll see a confirmation code. To assign payment to individual workers, just compare the confirmation codes stored in JATOS' results view to those stored in MTurk.

Confirmation code

- +
Skip to main content
Version: 3.6.x and earlier

Use MTurk

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 before you let real workers do it.

You will need​

  • A requester Mturk account
  • Your study running on a JATOS server
  • A description of the study (this can be the same as the one you included in the study description within JATOS)

On JATOS page​

In JATOS, go to the Study Toolbar ⟶ Worker & Batch Manager

JATOS GUI screenshot

  1. Open the Worker Setup of the batch you want to run

  2. Enable the MTurk worker type

  3. 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

On MTurk's page​

You first have to create a project in the MTurk interface:

  1. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project

  2. Complete the Enter Properties tab

  3. Click on the Design layout button in the bottom of the page.

  4. 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

  5. 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).

  6. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

    MTurk Schreenshot

What should happen​

When an MTurk worker finishes a study they'll see a confirmation code. To assign payment to individual workers, just compare the confirmation codes stored in JATOS' results view to those stored in MTurk.

Confirmation code

+ \ No newline at end of file diff --git a/3.6.x/Contact-us.html b/3.6.x/Contact-us.html index c537e03e3..3ac1dda6e 100644 --- a/3.6.x/Contact-us.html +++ b/3.6.x/Contact-us.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Contact us

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​

We recently started a subforum in the very nice CogSci.nl forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

Note: We recently migrated from Google Groups. Check it out, as you might find the answer you're looking for.

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.

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

- +
Skip to main content
Version: 3.6.x and earlier

Contact us

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​

We recently started a subforum in the very nice CogSci.nl forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

Note: We recently migrated from Google Groups. Check it out, as you might find the answer you're looking for.

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.

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

+ \ No newline at end of file diff --git a/3.6.x/Create-a-new-study.html b/3.6.x/Create-a-new-study.html index b2f0bf888..0df7d5327 100644 --- a/3.6.x/Create-a-new-study.html +++ b/3.6.x/Create-a-new-study.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Create a new study

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 or Adapt Pre written Code to run it in JATOS (Jatosify).

Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

Use a builder - OpenSesame/OSWeb and lab.js​

Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

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.

Press the New Study button in the header of your local JATOS. Then edit the study properties and add new components manually. All source code for your study has to got into the study assets folder you defined in the the study properties. 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) as a prototype and modify it bit by bit. Press on the Import button in the header and select the file of the study. Then see the source code in your study assets folder, which is usually in your JATOS installation folder.

- +
Skip to main content
Version: 3.6.x and earlier

Create a new study

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 or Adapt Pre written Code to run it in JATOS (Jatosify).

Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

Use a builder - OpenSesame/OSWeb and lab.js​

Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

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.

Press the New Study button in the header of your local JATOS. Then edit the study properties and add new components manually. All source code for your study has to got into the study assets folder you defined in the the study properties. 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) as a prototype and modify it bit by bit. Press on the Import button in the header and select the file of the study. Then see the source code in your study assets folder, which is usually in your JATOS installation folder.

+ \ No newline at end of file diff --git a/3.6.x/Cross-sectional-and-longitudinal-studies.html b/3.6.x/Cross-sectional-and-longitudinal-studies.html index b81e2e54f..7824a79b3 100644 --- a/3.6.x/Cross-sectional-and-longitudinal-studies.html +++ b/3.6.x/Cross-sectional-and-longitudinal-studies.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Write cross-sectional and longitudinal studies

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.
  2. run a between-participants study.
  3. 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 does just this.

1. Counterbalance conditions between participants​

The basic idea here is simple. Every time a new participant clicks on a worker 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" 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 for a more thorugh 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.

If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple links to each participant. If a participant runs a study with this link, JATOS will assign them a unique number. You can access the worker ID in your JavaScript through jatos.urlQueryParameters.workerId from the jatos.js library.

Using MTurk​

If you are recruiting participants through a MTurk, it's straightforward: You can access the worker ID in your JavaScript through jatos.urlQueryParameters.workerId.

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

If you select these options in Prolific, you'll be able to collect the Prolific ID from your JavaScript by using the jatos.js object 

var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

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: 

{
  "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: 

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.

- +
Skip to main content
Version: 3.6.x and earlier

Write cross-sectional and longitudinal studies

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.
  2. run a between-participants study.
  3. 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 does just this.

1. Counterbalance conditions between participants​

The basic idea here is simple. Every time a new participant clicks on a worker 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" 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 for a more thorugh 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.

If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple links to each participant. If a participant runs a study with this link, JATOS will assign them a unique number. You can access the worker ID in your JavaScript through jatos.urlQueryParameters.workerId from the jatos.js library.

Using MTurk​

If you are recruiting participants through a MTurk, it's straightforward: You can access the worker ID in your JavaScript through jatos.urlQueryParameters.workerId.

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

If you select these options in Prolific, you'll be able to collect the Prolific ID from your JavaScript by using the jatos.js object 

var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

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: 

{
  "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: 

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.

+ \ No newline at end of file diff --git a/3.6.x/Customize-JATOS-Home-Page.html b/3.6.x/Customize-JATOS-Home-Page.html index d548b4971..50e841915 100644 --- a/3.6.x/Customize-JATOS-Home-Page.html +++ b/3.6.x/Customize-JATOS-Home-Page.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Customize JATOS' Home Page

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/production.conf and add the URL under jatos.termsOfUseUrl. If left empty the info box is not shown.

Welcome Block (since JATOS v3.5.9)​

You can customize JATOS' home page to e.g.

  • show your university's logo,
  • add some introduction text, or
  • announce an upcoming event.

template customized home page

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.

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

  2. Click 'Use this template' button to create a copy of this repository

  3. Change the content of foobar-university-welcome.html to your needs

  4. Add necessary files (e.g. logo images) to your repository

  5. Configure JATOS: In your JATOS installation folder edit conf/production.conf - add jatos.brandingUrl:

    1. Easy but with rate limit

      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

    2. Better use GitHub pages

      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

  6. Restart JATOS

- +
Skip to main content
Version: 3.6.x and earlier

Customize JATOS' Home Page

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/production.conf and add the URL under jatos.termsOfUseUrl. If left empty the info box is not shown.

Welcome Block (since JATOS v3.5.9)​

You can customize JATOS' home page to e.g.

  • show your university's logo,
  • add some introduction text, or
  • announce an upcoming event.

template customized home page

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.

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

  2. Click 'Use this template' button to create a copy of this repository

  3. Change the content of foobar-university-welcome.html to your needs

  4. Add necessary files (e.g. logo images) to your repository

  5. Configure JATOS: In your JATOS installation folder edit conf/production.conf - add jatos.brandingUrl:

    1. Easy but with rate limit

      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

    2. Better use GitHub pages

      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

  6. Restart JATOS

+ \ No newline at end of file diff --git a/3.6.x/Data-Privacy-and-Ethics.html b/3.6.x/Data-Privacy-and-Ethics.html index 66cc84ac5..3a313a54b 100644 --- a/3.6.x/Data-Privacy-and-Ethics.html +++ b/3.6.x/Data-Privacy-and-Ethics.html @@ -10,13 +10,13 @@ - +
-
Skip to main content
Version: 3.6.x and earlier

Data Privacy and Ethics

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

(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 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, and not in a commercial server like Amazon or Qualtrics. 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 (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 (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 and jatos.addAbortButton that do exactly that.

  • Use encryption with your server instance. 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 JATOSIDS ( 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 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
  • 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)
  • 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.

E.g. JATOS_IDS_0:"batchId=108&componentId=306&componentPos=2&componentResultId=3867&creationTime=1524941205992&studyAssets=batch_chat_cambridge_workshop&jatosRun=RUN_COMPONENT_FINISHED&groupResultId=null&studyId=101&studyResultId=1346&workerId=1&workerType=Jatos"

This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

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 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"

- +
Skip to main content
Version: 3.6.x and earlier

Data Privacy and Ethics

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

(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 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, and not in a commercial server like Amazon or Qualtrics. 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 (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 (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 and jatos.addAbortButton that do exactly that.

  • Use encryption with your server instance. 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 JATOSIDS ( 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 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
  • 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)
  • 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.

E.g. JATOS_IDS_0:"batchId=108&componentId=306&componentPos=2&componentResultId=3867&creationTime=1524941205992&studyAssets=batch_chat_cambridge_workshop&jatosRun=RUN_COMPONENT_FINISHED&groupResultId=null&studyId=101&studyResultId=1346&workerId=1&workerType=Jatos"

This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

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 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"

+ \ No newline at end of file diff --git a/3.6.x/Deploy-to-a-server-installation.html b/3.6.x/Deploy-to-a-server-installation.html index cca39db35..852e33d3f 100644 --- a/3.6.x/Deploy-to-a-server-installation.html +++ b/3.6.x/Deploy-to-a-server-installation.html @@ -10,15 +10,15 @@ - +
Skip to main content
Version: 3.6.x and earlier

Deploy to a server installation

Usually you conveniently develop your study on your local computer where you have a local installation of JATOS. Then just use the export and import buttons in your installations to transfer the study to your JATOS server.

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.
  2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
  3. On your server installation, simply click Import.

Here's a little sketch of the same three steps above jzip workflow

If you have trouble with the export and you are using a Safari browser have a look into this issue in our Troubleshooting section.

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 black bar on top. A server installation has a light-grey bar.
  • A .jzip file is a normal .zip file. We just changed the name to make this process clearer. (JATOS users got confused and often tried to unzip the file they had downloaded, add HTML files in it, and re-zip it. This will lead to all sorts of problems. Don't do this. -You should do all modifications of files and study properties from the JATOS GUI.)
  • 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 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.
- +You should do all modifications of files and study properties from the JATOS GUI.)
  • 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 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.
    • + \ No newline at end of file diff --git a/3.6.x/End-page-after-your-study-finished.html b/3.6.x/End-page-after-your-study-finished.html index 36e50ca98..6c9857623 100644 --- a/3.6.x/End-page-after-your-study-finished.html +++ b/3.6.x/End-page-after-your-study-finished.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    End page - After your study finished

    1. Default​

    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 finshed. Maybe you want a different language or add a logo and different text or styling, then read on.

    2. endPage.html (since JATOS v3.5.1)​

    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 it won't show you the endPage.html but redirect you back to JATOS' GUI instead.

    3. Study Properties' End Redirect URL (since JATOS v3.5.1)​

    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

    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.

    Since version 3.6.1 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.

    • Study run link URL:

      http://myjatosdomain/publix/1/start?batchId=1&personalSingleWorkerId=1234&SONA_ID=123abc

    • End Redirect URL put in JATOS, 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

    4. jatos.endStudyAndRedirect (since JATOS v3.5.1) or jatos.endStudyAjax (all JATOS versions)​

    If you want to determine dynamically (i.e. in the 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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    End page - After your study finished

    1. Default​

    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 finshed. Maybe you want a different language or add a logo and different text or styling, then read on.

    2. endPage.html (since JATOS v3.5.1)​

    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 it won't show you the endPage.html but redirect you back to JATOS' GUI instead.

    3. Study Properties' End Redirect URL (since JATOS v3.5.1)​

    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

    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.

    Since version 3.6.1 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.

    • Study run link URL:

      http://myjatosdomain/publix/1/start?batchId=1&personalSingleWorkerId=1234&SONA_ID=123abc

    • End Redirect URL put in JATOS, 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

    4. jatos.endStudyAndRedirect (since JATOS v3.5.1) or jatos.endStudyAjax (all JATOS versions)​

    If you want to determine dynamically (i.e. in the 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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    + \ No newline at end of file diff --git a/3.6.x/Example-Group-Studies.html b/3.6.x/Example-Group-Studies.html index f66ed0aaa..cc74ae702 100644 --- a/3.6.x/Example-Group-Studies.html +++ b/3.6.x/Example-Group-Studies.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Worker & Batch Manager
    3. Expand the "Default Batch" ("" button in the left) to see the worker setup
    4. Now get your first worker: Expand (again with "") the Jatos Worker and click the Run button - and the study will start in a new browser tab
    5. Repeat for the second worker
    6. In both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab represents one worker who is running the Snake Game - but they are in the same group
    8. Optional: Add more snakes by adding more workers. You can try every worker type you want - it's of course not limited to Jatos Workers.
    9. Optional: Have a look at your Group in the Worker & and Batch Manager add see who the member workers are. -{% include image.html file="example-studies/Screenshot_snakeGame.png" alt="Snake Game" caption="" max-width="500" %}

    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.

    - +{% include image.html file="example-studies/Screenshot_snakeGame.png" alt="Snake Game" caption="" max-width="500" %}

    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.

    + \ No newline at end of file diff --git a/3.6.x/Expose-your-local-JATOS.html b/3.6.x/Expose-your-local-JATOS.html index d86d63efe..da5431729 100644 --- a/3.6.x/Expose-your-local-JATOS.html +++ b/3.6.x/Expose-your-local-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create worker links and send them to your participents. Remember to use JATOS under the ngrog.io address when you create worker links (and not your localhost one).

    More information on https://ngrok.com.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create worker links and send them to your participents. Remember to use JATOS under the localhost.run address when you create worker links (and not your localhost one).

    More information on http://localhost.run/.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create worker links and send them to your participents. Remember to use JATOS under the ngrog.io address when you create worker links (and not your localhost one).

    More information on https://ngrok.com.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create worker links and send them to your participents. Remember to use JATOS under the localhost.run address when you create worker links (and not your localhost one).

    More information on http://localhost.run/.

    + \ No newline at end of file diff --git a/3.6.x/Get-started.html b/3.6.x/Get-started.html index 04d3904db..bb12f8cd2 100644 --- a/3.6.x/Get-started.html +++ b/3.6.x/Get-started.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Get started

    Get started in 4 steps​

    1. Download JATOS and install a local instance

    2. Open JATOS' GUI by going to http://localhost:9000/jatos/login in your browser window

    3. Download and import an example study

      1. Download one of the Example Studies, e.g. the 'Go- / No-Go Task' with jsPsych. Do not unzip the downloaded file.

      2. Import the study into JATOS: Go to JATOS' GUI in your browser and click on Import Study in the header. Choose the .zip file you just downloaded. The imported study should appear in the sidebar on the left.

    4. 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).

      Here's a screenshot of a study's results view: Results View screenshot

    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/.

    Here's a screenshot of a component's properties view: -GUI screenshot

    - +GUI screenshot

    + \ No newline at end of file diff --git a/3.6.x/Install-JATOS-via-Docker.html b/3.6.x/Install-JATOS-via-Docker.html index aae8d3d09..9406c00dd 100644 --- a/3.6.x/Install-JATOS-via-Docker.html +++ b/3.6.x/Install-JATOS-via-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Install JATOS via Docker

    JATOS has a Docker image: 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).

    Install JATOS locally with a Docker container​

    1. Install Docker locally on your computer (not covered here)

    2. Go to your shell or command line interface

    3. Pull JATOS image

      • either latest:
      docker pull jatos/jatos:latest
      • or a specific one (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    4. Run JATOS (use your image version)

      docker run -d -p 9000:9000 jatos/jatos:latest

      The -d argument specifies to run this container in detached mode (in the backgroud) and the -p is responsible for the port mapping.

    5. You can check that the new container is running: In your browser go to localhost:9000 - it should show the JATOS login screen. Or use docker ps - in the line with jatos/jatos the status should say up.

    Troubleshooting: By removing the -d argument (e.g. docker run -p 9000:9000 jatos/jatos:latest) you get JATOS' logs printed in your shell - although you don't run it in detached mode in the background anymore.

    Troubleshooting 2nd: Although usually not necessary maybe you want to have a look into the running container and start a Bash terminal:

    docker exec -it running-jatos-container-id /bin/bash

    Change port​

    With Docker you can easily change JATOS' port (actually we change the port mapping of JATOS' docker container). Just use Docker -p argument and specify your port. E.g. to run JATOS on standard HTTP port 80 use:

    docker run -d -p 80:9000 jatos/jatos:latest

    Configure with environment variables​

    All environment variables that can be used to configure a normal JATOS server installation 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 a host with the IP 172.17.0.2 and with the default port 3306 use the following command (change username and password of your MySQL account):

    docker run -e JATOS_DB_URL='jdbc:mysql://172.17.0.2/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' -e JATOS_DB_USERNAME='root' -e JATOS_DB_PASSWORD='password' -e JATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver -e JATOS_JPA=mysqlPersistenceUnit -p 9000:9000 jatos/jatos:latest
    - +
    Skip to main content
    Version: 3.6.x and earlier

    Install JATOS via Docker

    JATOS has a Docker image: 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).

    Install JATOS locally with a Docker container​

    1. Install Docker locally on your computer (not covered here)

    2. Go to your shell or command line interface

    3. Pull JATOS image

      • either latest:
      docker pull jatos/jatos:latest
      • or a specific one (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    4. Run JATOS (use your image version)

      docker run -d -p 9000:9000 jatos/jatos:latest

      The -d argument specifies to run this container in detached mode (in the backgroud) and the -p is responsible for the port mapping.

    5. You can check that the new container is running: In your browser go to localhost:9000 - it should show the JATOS login screen. Or use docker ps - in the line with jatos/jatos the status should say up.

    Troubleshooting: By removing the -d argument (e.g. docker run -p 9000:9000 jatos/jatos:latest) you get JATOS' logs printed in your shell - although you don't run it in detached mode in the background anymore.

    Troubleshooting 2nd: Although usually not necessary maybe you want to have a look into the running container and start a Bash terminal:

    docker exec -it running-jatos-container-id /bin/bash

    Change port​

    With Docker you can easily change JATOS' port (actually we change the port mapping of JATOS' docker container). Just use Docker -p argument and specify your port. E.g. to run JATOS on standard HTTP port 80 use:

    docker run -d -p 80:9000 jatos/jatos:latest

    Configure with environment variables​

    All environment variables that can be used to configure a normal JATOS server installation 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 a host with the IP 172.17.0.2 and with the default port 3306 use the following command (change username and password of your MySQL account):

    docker run -e JATOS_DB_URL='jdbc:mysql://172.17.0.2/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' -e JATOS_DB_USERNAME='root' -e JATOS_DB_PASSWORD='password' -e JATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver -e JATOS_JPA=mysqlPersistenceUnit -p 9000:9000 jatos/jatos:latest
    + \ No newline at end of file diff --git a/3.6.x/Installation.html b/3.6.x/Installation.html index 6566e0bef..f32e7b01d 100644 --- a/3.6.x/Installation.html +++ b/3.6.x/Installation.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Installation

    Easy installation on your local computer - JATOS runs on MacOS, Windows and Linux

    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 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 in a variant bundled with Java.

    To run JATOS, you need Java 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 X / Linux) or command window (MS Windows). -If you don't have Java installed, you can either download and install it directly or download and install JATOS bundled with Java, according to your operating system.

    Installation MS Windows​

    1. Download the latest JATOS release (exchange 'xxx' with the current version)
    • Without Java: jatos-xxx.zip
    • Bundled with Java: jatos-xxx_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 more about why not.
    2. 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.
    3. All set! Now go to the browser of your choice and open http://localhost:9000/jatos/login. 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 X and Linux​

    1. Download the latest JATOS release (exchange 'xxx' with the current version)
      • Without Java: jatos-xxx.zip
      • For MacOS bundled with Java: jatos-xxx_mac_java.zip
      • For Linux bundled with Java: jatos-xxx_linux_java.zip
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. All set! Now go to the browser of your choice and open http://localhost:9000/jatos/login. 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 and play around with it.

    - +If you don't have Java installed, you can either download and install it directly or download and install JATOS bundled with Java, according to your operating system.

    Installation MS Windows​

    1. Download the latest JATOS release (exchange 'xxx' with the current version)
    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 more about why not.
    2. 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.
    3. All set! Now go to the browser of your choice and open http://localhost:9000/jatos/login. 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 X and Linux​

    1. Download the latest JATOS release (exchange 'xxx' with the current version)
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. All set! Now go to the browser of your choice and open http://localhost:9000/jatos/login. 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 and play around with it.

    + \ No newline at end of file diff --git a/3.6.x/JATOS-Tryout-Server.html b/3.6.x/JATOS-Tryout-Server.html index 6356881f7..ac0c81b19 100644 --- a/3.6.x/JATOS-Tryout-Server.html +++ b/3.6.x/JATOS-Tryout-Server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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 in an online environment.

    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, 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.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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 in an online environment.

    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, 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.

    + \ No newline at end of file diff --git a/3.6.x/JATOS-in-Amazons-Cloud-without-Docker.html b/3.6.x/JATOS-in-Amazons-Cloud-without-Docker.html index ff8cb7001..b3c614d74 100644 --- a/3.6.x/JATOS-in-Amazons-Cloud-without-Docker.html +++ b/3.6.x/JATOS-in-Amazons-Cloud-without-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    JATOS on AWS

    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 and applies here too. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too - I tested it with Ubuntu 14.04 and 16.04)
    3. 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.
    4. 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.)
    5. Get the latest JATOS bundled with Java (exchange x.x.x with the version you want) wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos-x.x.x-linux_java.zip
    6. unzip jatos-x.x.x-linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. Configure IP and port in conf/production.conf: Use the 'Private IP' from your instance description (the one that starts with 172.x.x.x) and port 80
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    - +
    Skip to main content
    Version: 3.6.x and earlier

    JATOS on AWS

    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 and applies here too. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too - I tested it with Ubuntu 14.04 and 16.04)
    3. 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.
    4. 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.)
    5. Get the latest JATOS bundled with Java (exchange x.x.x with the version you want) wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos-x.x.x-linux_java.zip
    6. unzip jatos-x.x.x-linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. Configure IP and port in conf/production.conf: Use the 'Private IP' from your instance description (the one that starts with 172.x.x.x) and port 80
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    + \ No newline at end of file diff --git a/3.6.x/JATOS-on-DigitalOcean.html b/3.6.x/JATOS-on-DigitalOcean.html index c586e8351..8c7882364 100644 --- a/3.6.x/JATOS-on-DigitalOcean.html +++ b/3.6.x/JATOS-on-DigitalOcean.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    JATOS on DigitalOcean

    On this page we want to explain how to install JATOS on a server running on DigitalOcean. We tried to keep this tutorial as easy as possible: if everything runs smoothly you don't have to use the terminal at all.

    DigitalOcean is a cloud provider (like AWS, Google Cloud, Azure etc.) that is comparatively easy to use and has good documentation. They offer something called Droplets and One-Click Apps which is just a fancy name for a pre-installed server in the cloud. And btw. we have no connections to DigitalOcean whatsoever.

    Keep in mind: A server in the cloud will cost money (circa $5 to $10 / month) and you will need a credit card.

    Setup a simple JATOS server on DigitalOcean​

    First we want to set up a simple JATOS server without encryption (HTTPS) or a domain name.

    1. Set up an account with DigitalOcean -you'll have to provide billing information.

    2. Use this link to create a Droplet with Docker on Ubuntu pre-installed. Do not press Create yet - we need to set up things first.

      Selected Marketplace with Docker on Ubuntu

      Your sreen should look similar to this one: Selected Marketplace (was One-Click App in past) with Docker on Ubuntu (currently it's called Docker 18.06.1-ce-3 on 18.04)

    3. Scroll down to Choose a size: Droplet size depends on your experiments. Common numbers are 1GB, 2GB, 4GB for a single researcher or group - or 8GB for an institutional server.

    4. Scroll down to Choose region: You can actually use any you want, but best is to choose one that is near to your participants to reduce loading time.

    5. Select additional options: Here activate User Data and copy+paste the following script in the text field:

      #!/bin/bash

      # Run JATOS as docker container
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      Droplet&#39;s User Data

      The User Data should look similar to this screenshot here

    6. You could also add an SSH key under Add your SSH keys. If you don't know what this is, just ignore it - you will still be able to access the server.

    7. Finally click the Create button

    8. Try out your JATOS: Now the server is being created which can take a couple seconds. You should get an email from DigitalOcean with your server's (aka Droplet) name, IP address, username and password. Copy the IP into your browser's address bar and if everything went well, you will see a JATOS login screen.

    9. Log into JATOS with ‘admin’ and password ‘admin’

    10. The first thing you should do is change your admin password:

      1. Click on ‘Admin (admin) in top-right header
      2. Click ‘Change Password’

    Voila, you have your own JATOS server.

    Although usually not necessary, you can also access your server via SSH: ssh root@xx.xx.xx.xx (exchange xx.xx.xx.xx with your IP from the email). Use the password from the email. The first time you will be asked to change your password.

    Deleting your server​

    Deleting the server is straightforward. In DigitalOcean, in the left menu of your Droplet choose Destroy. DigitalOcean charges you by second. So if you want to create a new JATOS server because something went wrong, just Destroy the old one and start over.

    Now, you might want to use a nicer address than an IP and add some encryption-safety with HTTPS to your server - then read on.

    Add HTTPS with Traefik and use your own domain name​

    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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source and free to use.

    Buy 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. 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.

    To create a JATOS server with Traefik follow the instructions of the first paragraph (Setup a simple JATOS server on DigitalOcean) but in the User Data field of Select additional options put the following script:

    #!/bin/bash

    DOMAIN_NAME="my.domain.name"
    EMAIL="my.email@foo.com"

    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/docker-compose.yaml > /root/docker-compose.yaml
    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/traefik.toml > /root/traefik.toml

    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/docker-compose.yaml
    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/traefik.toml
    sed -i "s/<EMAIL>/${EMAIL}/g" /root/traefik.toml

    touch /root/acme.json
    chmod 600 /root/acme.json
    docker network create proxy
    docker-compose -f /root/docker-compose.yaml up -d

    Exchange my.domain.name and my.email@foo.com with your own domain name and email address. Your email we need for encryption with Let's Encrypt.

    This script downloads two config files, one for Traefik and one for Docker Compose. If you are interested you can examine them under https://github.com/JATOS/JATOS/blob/main/deploy/docker-compose.yaml and https://github.com/JATOS/JATOS/blob/main/deploy/traefik.toml. Docker Compose will start JATOS' and Traefik's container for us.

    After you've created your Droplet you still have to point your domain name to your server's IP address. This involves dealing with things like A records or AAAA records or DNS servers and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Then as a last step, after your domain name points to your server's IP, you have to reset your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and use HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption on your domain name.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    JATOS on DigitalOcean

    On this page we want to explain how to install JATOS on a server running on DigitalOcean. We tried to keep this tutorial as easy as possible: if everything runs smoothly you don't have to use the terminal at all.

    DigitalOcean is a cloud provider (like AWS, Google Cloud, Azure etc.) that is comparatively easy to use and has good documentation. They offer something called Droplets and One-Click Apps which is just a fancy name for a pre-installed server in the cloud. And btw. we have no connections to DigitalOcean whatsoever.

    Keep in mind: A server in the cloud will cost money (circa $5 to $10 / month) and you will need a credit card.

    Setup a simple JATOS server on DigitalOcean​

    First we want to set up a simple JATOS server without encryption (HTTPS) or a domain name.

    1. Set up an account with DigitalOcean -you'll have to provide billing information.

    2. Use this link to create a Droplet with Docker on Ubuntu pre-installed. Do not press Create yet - we need to set up things first.

      Selected Marketplace with Docker on Ubuntu

      Your sreen should look similar to this one: Selected Marketplace (was One-Click App in past) with Docker on Ubuntu (currently it's called Docker 18.06.1-ce-3 on 18.04)

    3. Scroll down to Choose a size: Droplet size depends on your experiments. Common numbers are 1GB, 2GB, 4GB for a single researcher or group - or 8GB for an institutional server.

    4. Scroll down to Choose region: You can actually use any you want, but best is to choose one that is near to your participants to reduce loading time.

    5. Select additional options: Here activate User Data and copy+paste the following script in the text field:

      #!/bin/bash

      # Run JATOS as docker container
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      Droplet&#39;s User Data

      The User Data should look similar to this screenshot here

    6. You could also add an SSH key under Add your SSH keys. If you don't know what this is, just ignore it - you will still be able to access the server.

    7. Finally click the Create button

    8. Try out your JATOS: Now the server is being created which can take a couple seconds. You should get an email from DigitalOcean with your server's (aka Droplet) name, IP address, username and password. Copy the IP into your browser's address bar and if everything went well, you will see a JATOS login screen.

    9. Log into JATOS with ‘admin’ and password ‘admin’

    10. The first thing you should do is change your admin password:

      1. Click on ‘Admin (admin) in top-right header
      2. Click ‘Change Password’

    Voila, you have your own JATOS server.

    Although usually not necessary, you can also access your server via SSH: ssh root@xx.xx.xx.xx (exchange xx.xx.xx.xx with your IP from the email). Use the password from the email. The first time you will be asked to change your password.

    Deleting your server​

    Deleting the server is straightforward. In DigitalOcean, in the left menu of your Droplet choose Destroy. DigitalOcean charges you by second. So if you want to create a new JATOS server because something went wrong, just Destroy the old one and start over.

    Now, you might want to use a nicer address than an IP and add some encryption-safety with HTTPS to your server - then read on.

    Add HTTPS with Traefik and use your own domain name​

    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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source and free to use.

    Buy 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. 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.

    To create a JATOS server with Traefik follow the instructions of the first paragraph (Setup a simple JATOS server on DigitalOcean) but in the User Data field of Select additional options put the following script:

    #!/bin/bash

    DOMAIN_NAME="my.domain.name"
    EMAIL="my.email@foo.com"

    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/docker-compose.yaml > /root/docker-compose.yaml
    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/traefik.toml > /root/traefik.toml

    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/docker-compose.yaml
    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/traefik.toml
    sed -i "s/<EMAIL>/${EMAIL}/g" /root/traefik.toml

    touch /root/acme.json
    chmod 600 /root/acme.json
    docker network create proxy
    docker-compose -f /root/docker-compose.yaml up -d

    Exchange my.domain.name and my.email@foo.com with your own domain name and email address. Your email we need for encryption with Let's Encrypt.

    This script downloads two config files, one for Traefik and one for Docker Compose. If you are interested you can examine them under https://github.com/JATOS/JATOS/blob/main/deploy/docker-compose.yaml and https://github.com/JATOS/JATOS/blob/main/deploy/traefik.toml. Docker Compose will start JATOS' and Traefik's container for us.

    After you've created your Droplet you still have to point your domain name to your server's IP address. This involves dealing with things like A records or AAAA records or DNS servers and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Then as a last step, after your domain name points to your server's IP, you have to reset your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and use HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption on your domain name.

    + \ No newline at end of file diff --git a/3.6.x/JATOS-on-a-server.html b/3.6.x/JATOS-on-a-server.html index bcb87071a..e9dbb885b 100644 --- a/3.6.x/JATOS-on-a-server.html +++ b/3.6.x/JATOS-on-a-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. You can install it

    If you don't know much about server administration the DigitalOcean page might be best for you.

    Installation on a server​

    The actual JATOS instance on a server isn't too different from a local one. It basically involves telling JATOS which IP address and port it should use and (optionally) replace the embedded database with a MySQL one. There are other issues however, not directly related to JATOS, that you should consider when setting up a server. These include: setting up automatic, regular backups of your data, an automatic restart of JATOS after a server reboot, encryption, additional HTTP server, etc.

    1. Install Java​

    We've produced multiple versions of JATOS. The simplest version is JATOS alone, but other versions are bundled with Java JRE. On a server, it's best (though not necessary) to install JATOS without a bundled Java. This will make it easier to upgrade to new Java releases. Prior to JATOS v3.4.1 Java 8 is necessary - from v3.4.1 on both Java 8 and 11 are fine.

    2. [Optional] Install MySQL​

    See JATOS with MySQL

    3. Install JATOS​

    1. Download JATOS

      E.g. with wget for the version 3.5.4:

      wget https://github.com/JATOS/JATOS/releases/download/v3.5.4/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed.

    3. Check that the file loader.sh in the JATOS folder is executable.

    4. Check that JATOS starts with loader.sh start|restart|stop

    4. Configuration​

    If JATOS runs locally it's usually not necessary to change the defaults but on a server you probably want to set up the IP and port or maybe use a different database and change the path of the study assets root folder. These docs have an extra page on how to Configure JATOS on a Server.

    5. Change Admin's password​

    Every JATOS installation comes with an Admin user that has the default password 'admin'. You must change it before the server goes live. This can be done in JATOS' GUI:

    1. Start JATOS and in a browser go to JATOS login page http://my-jatos-domain/jatos
    2. Login as 'admin' with password 'admin'
    3. Click on 'Admin (admin) in top-right header
    4. Click 'Change Password'

    6. Check JATOS' test page​

    JATOS comes with a handy test page: in the browser go to http://my-jatos-domain/jatos/admin, then click Tests and check that all tests are 'OK' (in older version the test page is under http://my-jatos-domain/jatos/test).

    7. [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    8. [Optional] Turn on user session validation​

    More here.

    9. [Optional] Auto-start JATOS​

    It's nice to have JATOS starts automatically after a start or a reboot of your machine. Choose between one of the two possibilities: 1) via a systemd service (JATOS version >= 3.1.6, recommended), or 2) via a init.d script.

    1) Via systemd service (JATOS version >= 3.1.6, recommended)​

    Create a systemd service file for JATOS 

    vim /etc/systemd/system/jatos.service

    and put the following text inside. 

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Change the paths and the user according to your JATOS path and the user you want to start JATOS with.

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need systemctl daemon-reload jatos.service to let the system know.

    2) Via /etc/init.d script​

    It's easy to turn the loader.sh script into an init script for a daemon.

    1. Copy the loader.sh script to /etc/init.d/

    2. Rename it to jatos

    3. Change access permission with chmod og+x jatos

    4. Edit /etc/init.d/jatos

      1. Comment out the line that defines the JATOS location dir="$( cd "$( dirname "$0" )" && pwd )"

      2. Add a new locatoin dir= with the path to your JATOS installation

        The beginning of your /etc/init.d/jatos should look like:

        #!/bin/bash
        # JATOS loader for Linux and MacOS X

        # Change IP address and port here
        # Alternatively you can use command-line arguments -Dhttp.address and -Dhttp.port
        address="127.0.0.1"
        port="9000"

        # Don't change after here unless you know what you're doing
        ###########################################################

        # Get JATOS directory
        #dir="$( cd "$( dirname "$0" )" && pwd )"
        dir="/path/to/my/JATOS/installation"
        ...

    5. Make it auto-start with the command sudo update-rc.d jatos defaults

    Now JATOS starts automatically when you start your server and stops when you shut it down. You can also use the init script yourself like any other init script with sudo /etc/init.d/jatos start|stop|restart.

    10. [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularily.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of two parts (1.) the data stored in the database and (2.) your study assets folder that contains all the web files (e.g. HTML, JavaScript, images). Both have to be backed up to be able to restore them later on.

    1. Database

      • MySQL - If you use a MySQL database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.
      • H2 - There are at least two ways: one easy (but unofficial) and one official:
        1. Copy & paste the db file - It's important to stop JATOS before doing a backup or restoring a H2 database this way. If you do not stop JATOS your data might be corrupted. You can just backup the folder my-jatos-path/database. In case you want to restore an older version from the backup just replace the current version of the folder with the backed-up version.
        2. Via H2's upgrade, backup, and restore tool

    2. study_assets_root folder - This is the folder where all your study's assets (e.g. HTML, JS, CSS, images) are stored. You can just make a backup of your study assets folder. If you want to return to a prior version replace the current folder with the backed-up version.

    3. result_uploads folder - This folder contains the files, that were uploaded during a study run. You can just make a backup of your results upload folder. If you want to return to a prior version replace the current folder with the backed-up version.

    4. study_logs folder - Contains the study logs

    Remember, a backup has to be done of all four the folders, database and the study_assets_root and result_uploads and study_logs.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. You can install it

    If you don't know much about server administration the DigitalOcean page might be best for you.

    Installation on a server​

    The actual JATOS instance on a server isn't too different from a local one. It basically involves telling JATOS which IP address and port it should use and (optionally) replace the embedded database with a MySQL one. There are other issues however, not directly related to JATOS, that you should consider when setting up a server. These include: setting up automatic, regular backups of your data, an automatic restart of JATOS after a server reboot, encryption, additional HTTP server, etc.

    1. Install Java​

    We've produced multiple versions of JATOS. The simplest version is JATOS alone, but other versions are bundled with Java JRE. On a server, it's best (though not necessary) to install JATOS without a bundled Java. This will make it easier to upgrade to new Java releases. Prior to JATOS v3.4.1 Java 8 is necessary - from v3.4.1 on both Java 8 and 11 are fine.

    2. [Optional] Install MySQL​

    See JATOS with MySQL

    3. Install JATOS​

    1. Download JATOS

      E.g. with wget for the version 3.5.4:

      wget https://github.com/JATOS/JATOS/releases/download/v3.5.4/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed.

    3. Check that the file loader.sh in the JATOS folder is executable.

    4. Check that JATOS starts with loader.sh start|restart|stop

    4. Configuration​

    If JATOS runs locally it's usually not necessary to change the defaults but on a server you probably want to set up the IP and port or maybe use a different database and change the path of the study assets root folder. These docs have an extra page on how to Configure JATOS on a Server.

    5. Change Admin's password​

    Every JATOS installation comes with an Admin user that has the default password 'admin'. You must change it before the server goes live. This can be done in JATOS' GUI:

    1. Start JATOS and in a browser go to JATOS login page http://my-jatos-domain/jatos
    2. Login as 'admin' with password 'admin'
    3. Click on 'Admin (admin) in top-right header
    4. Click 'Change Password'

    6. Check JATOS' test page​

    JATOS comes with a handy test page: in the browser go to http://my-jatos-domain/jatos/admin, then click Tests and check that all tests are 'OK' (in older version the test page is under http://my-jatos-domain/jatos/test).

    7. [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    8. [Optional] Turn on user session validation​

    More here.

    9. [Optional] Auto-start JATOS​

    It's nice to have JATOS starts automatically after a start or a reboot of your machine. Choose between one of the two possibilities: 1) via a systemd service (JATOS version >= 3.1.6, recommended), or 2) via a init.d script.

    1) Via systemd service (JATOS version >= 3.1.6, recommended)​

    Create a systemd service file for JATOS 

    vim /etc/systemd/system/jatos.service

    and put the following text inside. 

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Change the paths and the user according to your JATOS path and the user you want to start JATOS with.

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need systemctl daemon-reload jatos.service to let the system know.

    2) Via /etc/init.d script​

    It's easy to turn the loader.sh script into an init script for a daemon.

    1. Copy the loader.sh script to /etc/init.d/

    2. Rename it to jatos

    3. Change access permission with chmod og+x jatos

    4. Edit /etc/init.d/jatos

      1. Comment out the line that defines the JATOS location dir="$( cd "$( dirname "$0" )" && pwd )"

      2. Add a new locatoin dir= with the path to your JATOS installation

        The beginning of your /etc/init.d/jatos should look like:

        #!/bin/bash
        # JATOS loader for Linux and MacOS X

        # Change IP address and port here
        # Alternatively you can use command-line arguments -Dhttp.address and -Dhttp.port
        address="127.0.0.1"
        port="9000"

        # Don't change after here unless you know what you're doing
        ###########################################################

        # Get JATOS directory
        #dir="$( cd "$( dirname "$0" )" && pwd )"
        dir="/path/to/my/JATOS/installation"
        ...

    5. Make it auto-start with the command sudo update-rc.d jatos defaults

    Now JATOS starts automatically when you start your server and stops when you shut it down. You can also use the init script yourself like any other init script with sudo /etc/init.d/jatos start|stop|restart.

    10. [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularily.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of two parts (1.) the data stored in the database and (2.) your study assets folder that contains all the web files (e.g. HTML, JavaScript, images). Both have to be backed up to be able to restore them later on.

    1. Database

      • MySQL - If you use a MySQL database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.
      • H2 - There are at least two ways: one easy (but unofficial) and one official:
        1. Copy & paste the db file - It's important to stop JATOS before doing a backup or restoring a H2 database this way. If you do not stop JATOS your data might be corrupted. You can just backup the folder my-jatos-path/database. In case you want to restore an older version from the backup just replace the current version of the folder with the backed-up version.
        2. Via H2's upgrade, backup, and restore tool

    2. study_assets_root folder - This is the folder where all your study's assets (e.g. HTML, JS, CSS, images) are stored. You can just make a backup of your study assets folder. If you want to return to a prior version replace the current folder with the backed-up version.

    3. result_uploads folder - This folder contains the files, that were uploaded during a study run. You can just make a backup of your results upload folder. If you want to return to a prior version replace the current folder with the backed-up version.

    4. study_logs folder - Contains the study logs

    Remember, a backup has to be done of all four the folders, database and the study_assets_root and result_uploads and study_logs.

    + \ No newline at end of file diff --git a/3.6.x/JATOS-with-Apache.html b/3.6.x/JATOS-with-Apache.html index 8c8ca030a..90b892220 100644 --- a/3.6.x/JATOS-with-Apache.html +++ b/3.6.x/JATOS-with-Apache.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    JATOS with Apache

    This is an example of a configuration of Apache as a 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 allow encryption.

    Here I used Apache 2.4.18 on a Ubuntu system. I recommend to use at least version 2.4 since JATOS relies on WebSockets that aren't supported by earlier Apache versions.

    I had to add some modules to Apache to get it working:

    sudo a2enmod rewrite
    sudo a2enmod proxy_wstunnel
    sudo a2enmod proxy
    sudo a2enmod headers
    sudo a2enmod ssl
    sudo a2enmod lbmethod_byrequests
    sudo a2enmod proxy_balancer
    sudo a2enmod proxy_http
    sudo a2enmod remoteip

    The following is an example of a proxy config with Apache. I stored it in /etc/apache2/sites-available/example.com.conf and added it to Apache with the command sudo a2ensite example.com.conf.

    • It enforces access via HTTPS by redirecting all HTTP traffic.
    • 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.
    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # Needed for JATOS to get the correct host and protocol
      ProxyPreserveHost On
      RequestHeader set X-Forwarded-Proto "https"
      RequestHeader set X-Forwarded-Ssl "on"
      
      # 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/
    </VirtualHost>
    - +
    Skip to main content
    Version: 3.6.x and earlier

    JATOS with Apache

    This is an example of a configuration of Apache as a 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 allow encryption.

    Here I used Apache 2.4.18 on a Ubuntu system. I recommend to use at least version 2.4 since JATOS relies on WebSockets that aren't supported by earlier Apache versions.

    I had to add some modules to Apache to get it working:

    sudo a2enmod rewrite
    sudo a2enmod proxy_wstunnel
    sudo a2enmod proxy
    sudo a2enmod headers
    sudo a2enmod ssl
    sudo a2enmod lbmethod_byrequests
    sudo a2enmod proxy_balancer
    sudo a2enmod proxy_http
    sudo a2enmod remoteip

    The following is an example of a proxy config with Apache. I stored it in /etc/apache2/sites-available/example.com.conf and added it to Apache with the command sudo a2ensite example.com.conf.

    • It enforces access via HTTPS by redirecting all HTTP traffic.
    • 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.
    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # Needed for JATOS to get the correct host and protocol
      ProxyPreserveHost On
      RequestHeader set X-Forwarded-Proto "https"
      RequestHeader set X-Forwarded-Ssl "on"
      
      # 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/
    </VirtualHost>
    + \ No newline at end of file diff --git a/3.6.x/JATOS-with-MySQL.html b/3.6.x/JATOS-with-MySQL.html index 426aa3b5f..6dcdbbee3 100644 --- a/3.6.x/JATOS-with-MySQL.html +++ b/3.6.x/JATOS-with-MySQL.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    JATOS with MySQL

    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 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 (although we had no problems with H2 so far)

    Installation​

    One could install the external database on the same server as JATOS is running or on an extra server depending on ones need.

    There are many manuals out there, e.g. this one. One way to set up MySQL:

    1. Install MySQL, e.g. on Ubuntu

      JATOS requires MySQL >= 5.7 (8.x is fine)

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword';

      Remember your username and password. You need them when configuring JATOS later on.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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.

    Configure JATOS​

    There are three ways to set up JATOS to work with a MySQL database. If you are in doubt use 'production.conf'.

    1. Via JATOS config file which is in your JATOS folder in the conf folder: conf/production.conf

      Change IP, port, username and password to your needs.

      db.default.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      db.default.user="jatosuser"
      db.default.password="mypassword"
      db.default.driver=com.mysql.cj.jdbc.Driver

      Always restart JATOS after making any changes to the configuration (e.g. with ./loader.sh restart)

    2. Via command-line arguments:

      • -DJATOS_DB_URL - specifies the URL to the database
      • -DJATOS_DB_USERNAME - set your username
      • -DJATOS_DB_PASSWORD - set your password
      • -DJATOS_DB_DRIVER - always com.mysql.cj.jdbc.Driver for MySQL

      E.g. to connect to a MySQL running on 127.0.0.1 and port 3306 use (but change username and password):

      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=sa -DJATOS_DB_PASSWORD=sa -DJATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver

    3. Via environment variables (change IP, port, username and password)

      export JATOS_DB_URL="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      export JATOS_DB_USERNAME=jatosuser
      export JATOS_DB_PASSWORD='mypassword'
      export 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. In older JATOS versions you can find this DB URL field under '/jatos/test'. Another way is by looking in the logs: you should see a line after JATOS started similar to this (with your database URI):

    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 now.

    [Optional] Deactivate MySQL's binary log​

    MySQL's binary logs (also called binlogs) serve two purposes: replication and data recovery. More can be found in MySQLs documentation.

    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's config but on many systems they are under /var/lib/mysql. If you have a single MySQL instance (and therefore do not use replication) and you do not need MySQL's 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 config (details). 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:

    # 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 for the changes to take effect.

    [Optional] Increase 'max_allowed_packet' size in older MySQLs​

    If you have an older MySQL (< 8.x.x) and your experiments will have large resut data you might want to increase the '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

    From 8.x.x the 'max_allowed_packet' is by default 64MB and this is usually more than enough. But in version smaller than 8.x.x 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 config. On many Linux systems the config is in /etc/mysql/mysql.conf.d/mysqld.cnf. E.g. to set it to 64MB:

    max_allowed_packet=64M

    You have to restart MySQL for the changes to take effect.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    JATOS with MySQL

    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 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 (although we had no problems with H2 so far)

    Installation​

    One could install the external database on the same server as JATOS is running or on an extra server depending on ones need.

    There are many manuals out there, e.g. this one. One way to set up MySQL:

    1. Install MySQL, e.g. on Ubuntu

      JATOS requires MySQL >= 5.7 (8.x is fine)

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword';

      Remember your username and password. You need them when configuring JATOS later on.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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.

    Configure JATOS​

    There are three ways to set up JATOS to work with a MySQL database. If you are in doubt use 'production.conf'.

    1. Via JATOS config file which is in your JATOS folder in the conf folder: conf/production.conf

      Change IP, port, username and password to your needs.

      db.default.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      db.default.user="jatosuser"
      db.default.password="mypassword"
      db.default.driver=com.mysql.cj.jdbc.Driver

      Always restart JATOS after making any changes to the configuration (e.g. with ./loader.sh restart)

    2. Via command-line arguments:

      • -DJATOS_DB_URL - specifies the URL to the database
      • -DJATOS_DB_USERNAME - set your username
      • -DJATOS_DB_PASSWORD - set your password
      • -DJATOS_DB_DRIVER - always com.mysql.cj.jdbc.Driver for MySQL

      E.g. to connect to a MySQL running on 127.0.0.1 and port 3306 use (but change username and password):

      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=sa -DJATOS_DB_PASSWORD=sa -DJATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver

    3. Via environment variables (change IP, port, username and password)

      export JATOS_DB_URL="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      export JATOS_DB_USERNAME=jatosuser
      export JATOS_DB_PASSWORD='mypassword'
      export 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. In older JATOS versions you can find this DB URL field under '/jatos/test'. Another way is by looking in the logs: you should see a line after JATOS started similar to this (with your database URI):

    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 now.

    [Optional] Deactivate MySQL's binary log​

    MySQL's binary logs (also called binlogs) serve two purposes: replication and data recovery. More can be found in MySQLs documentation.

    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's config but on many systems they are under /var/lib/mysql. If you have a single MySQL instance (and therefore do not use replication) and you do not need MySQL's 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 config (details). 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:

    # 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 for the changes to take effect.

    [Optional] Increase 'max_allowed_packet' size in older MySQLs​

    If you have an older MySQL (< 8.x.x) and your experiments will have large resut data you might want to increase the '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

    From 8.x.x the 'max_allowed_packet' is by default 64MB and this is usually more than enough. But in version smaller than 8.x.x 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 config. On many Linux systems the config is in /etc/mysql/mysql.conf.d/mysqld.cnf. E.g. to set it to 64MB:

    max_allowed_packet=64M

    You have to restart MySQL for the changes to take effect.

    + \ No newline at end of file diff --git a/3.6.x/JATOS-with-Nginx.html b/3.6.x/JATOS-with-Nginx.html index 34fbb4fbe..83eafcf3a 100644 --- a/3.6.x/JATOS-with-Nginx.html +++ b/3.6.x/JATOS-with-Nginx.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    JATOS with Nginx

    These are examples for configurations of Nginx as a proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common. They support WebSockets for JATOS' group studies.

    The following two configs are the content of /etc/nginx/nginx.conf. Change them 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. This proxy_set_header X-Forwarded-* is necessary to tell JATOS the original requester's IP address - please leave it unchanged.

    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.

    A JATOS server that handles sensitive or private data should always use encryption (HTTPS).

    With HTTPS​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;
    include /etc/nginx/modules-enabled/*.conf;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile             on;
            tcp_nopush           on;
            tcp_nodelay          on;
            keepalive_timeout    65;
            client_max_body_size 500M;

            include      /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto https;
            proxy_set_header   X-Forwarded-Ssl on;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            # redirect http to https
            server {
                    listen      80;
                    server_name www.example.com;
                    rewrite     ^ https://www.example.com$request_uri? permanent;
            }

            server {
                    listen        443 ssl;
                    server_name   www.example.com;

                    keepalive_timeout    70;

                    ssl_certificate      /etc/ssl/certs/localhost.crt;
                    ssl_certificate_key  /etc/ssl/private/localhost.key;

                    ssl_protocols             TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
                    ssl_prefer_server_ciphers on;

                    # websocket location (JATOS' group and batch channel and the test page)
                    location ~ "/(jatos/testWebSocket|publix/[\d]+/(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
                    #location /jatos {
                    #       allow           192.168.1.0/24;
                    #       deny            all;
                    #       proxy_pass      http://jatos-backend;
                    #}

                    # all other traffic
                    location / {
                            proxy_pass              http://jatos-backend;
                    }
                    
                    # restrict access to JATOS' GUI to local network 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;
                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }

    With HTTPS and Docker​

    Have a look at github.com/robinsonkwame/jatos-https-docker-compose for a good example in how to do this (Thanks to Kwame Porter Robinson)

    Simple without encryption​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile on;
            keepalive_timeout 65;
            client_max_body_size 500M;

            include /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto http;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            server {
                    listen               80;

                    keepalive_timeout    70;
                    server_name          www.example.com;

                    # websocket location (JATOS' group and batch channel and the test page)
                    location ~ "^/(jatos/testWebSocket|publix/[\d]+/(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
                    #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;

                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }
    - +
    Skip to main content
    Version: 3.6.x and earlier

    JATOS with Nginx

    These are examples for configurations of Nginx as a proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common. They support WebSockets for JATOS' group studies.

    The following two configs are the content of /etc/nginx/nginx.conf. Change them 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. This proxy_set_header X-Forwarded-* is necessary to tell JATOS the original requester's IP address - please leave it unchanged.

    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.

    A JATOS server that handles sensitive or private data should always use encryption (HTTPS).

    With HTTPS​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;
    include /etc/nginx/modules-enabled/*.conf;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile             on;
            tcp_nopush           on;
            tcp_nodelay          on;
            keepalive_timeout    65;
            client_max_body_size 500M;

            include      /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto https;
            proxy_set_header   X-Forwarded-Ssl on;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            # redirect http to https
            server {
                    listen      80;
                    server_name www.example.com;
                    rewrite     ^ https://www.example.com$request_uri? permanent;
            }

            server {
                    listen        443 ssl;
                    server_name   www.example.com;

                    keepalive_timeout    70;

                    ssl_certificate      /etc/ssl/certs/localhost.crt;
                    ssl_certificate_key  /etc/ssl/private/localhost.key;

                    ssl_protocols             TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
                    ssl_prefer_server_ciphers on;

                    # websocket location (JATOS' group and batch channel and the test page)
                    location ~ "/(jatos/testWebSocket|publix/[\d]+/(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
                    #location /jatos {
                    #       allow           192.168.1.0/24;
                    #       deny            all;
                    #       proxy_pass      http://jatos-backend;
                    #}

                    # all other traffic
                    location / {
                            proxy_pass              http://jatos-backend;
                    }
                    
                    # restrict access to JATOS' GUI to local network 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;
                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }

    With HTTPS and Docker​

    Have a look at github.com/robinsonkwame/jatos-https-docker-compose for a good example in how to do this (Thanks to Kwame Porter Robinson)

    Simple without encryption​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile on;
            keepalive_timeout 65;
            client_max_body_size 500M;

            include /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto http;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            server {
                    listen               80;

                    keepalive_timeout    70;
                    server_name          www.example.com;

                    # websocket location (JATOS' group and batch channel and the test page)
                    location ~ "^/(jatos/testWebSocket|publix/[\d]+/(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
                    #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;

                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }
    + \ No newline at end of file diff --git a/3.6.x/Manage-Results.html b/3.6.x/Manage-Results.html index ee747d1bf..f4d308b26 100644 --- a/3.6.x/Manage-Results.html +++ b/3.6.x/Manage-Results.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Manage Results

    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

    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

    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

    Selecting Results​

    Prior to JATOS version 3.3.1 you could select/deselect a specific result by clicking anywhere on the row. Selected results change color to gray.

    From version 3.3.1 on there is a checkbox on the left side of each row.

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export​

    Export Result Data​

    Once you selected the results you're interested in, click Export Results and Selected and you will download a text file that contains your results. Each line in this text file represents result data from one component. Alternatively you can also select All to get all result data.

    Results View screenshot

    Export Result Files (JATOS version >= 3.5.1)​

    Here you can download the result files that were uploaded during study runs. You can download single files by just clicking on them. Or similar to exporting result data select the lines you are interested in and download them with Export Files and Selected. Alternatively you can also select All to get all files.

    Results View screenshot

    Export Metadata (JATOS version >= 3.3.1)​

    Sometimes one is also interested in the metadata, that is what's in the actual table fields ("Result ID", "Start Time" , "Last Seen", ...). For this click on Export Metadata and the metadata of the selected results will be downloaded in CSV format.

    Results View screenshot

    Delete Results​

    You can click Delete to remove all or only some selected results (result data + result files + metadata). Keep in mind there's no undo function for this.

    Results View screenshot

    Table Columns​

    You can show and hide the columns displayed in the table with the drop-down menu under the Customize button (in older versions Display Columns).

    Results View screenshot

    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.

    Start Time - Time (set at the server's time zone) at which the first component of the study was started.

    End Time - Time (set at the server's time zone) 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.

    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 that ran the study.

    MTurk Worker ID (Confirmation Code) - Only applies to studies run by MTurk workers. An identifier given by Amazon Mechanical Turk's, not by JATOS. 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 - (Components only) Size of the result data as it is stored in the database

    Files (Size) - (Components only) List of the uploaded result files with their size in brackets

    State

    Possible states for study results are:

    • PRE - Preview of study (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.)
    • RESULTDATA_POSTED - The first time this component sent result data or files.
    • 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 or jatos.abortStudy.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Manage Results

    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

    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

    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

    Selecting Results​

    Prior to JATOS version 3.3.1 you could select/deselect a specific result by clicking anywhere on the row. Selected results change color to gray.

    From version 3.3.1 on there is a checkbox on the left side of each row.

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export​

    Export Result Data​

    Once you selected the results you're interested in, click Export Results and Selected and you will download a text file that contains your results. Each line in this text file represents result data from one component. Alternatively you can also select All to get all result data.

    Results View screenshot

    Export Result Files (JATOS version >= 3.5.1)​

    Here you can download the result files that were uploaded during study runs. You can download single files by just clicking on them. Or similar to exporting result data select the lines you are interested in and download them with Export Files and Selected. Alternatively you can also select All to get all files.

    Results View screenshot

    Export Metadata (JATOS version >= 3.3.1)​

    Sometimes one is also interested in the metadata, that is what's in the actual table fields ("Result ID", "Start Time" , "Last Seen", ...). For this click on Export Metadata and the metadata of the selected results will be downloaded in CSV format.

    Results View screenshot

    Delete Results​

    You can click Delete to remove all or only some selected results (result data + result files + metadata). Keep in mind there's no undo function for this.

    Results View screenshot

    Table Columns​

    You can show and hide the columns displayed in the table with the drop-down menu under the Customize button (in older versions Display Columns).

    Results View screenshot

    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.

    Start Time - Time (set at the server's time zone) at which the first component of the study was started.

    End Time - Time (set at the server's time zone) 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.

    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 that ran the study.

    MTurk Worker ID (Confirmation Code) - Only applies to studies run by MTurk workers. An identifier given by Amazon Mechanical Turk's, not by JATOS. 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 - (Components only) Size of the result data as it is stored in the database

    Files (Size) - (Components only) List of the uploaded result files with their size in brackets

    State

    Possible states for study results are:

    • PRE - Preview of study (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.)
    • RESULTDATA_POSTED - The first time this component sent result data or files.
    • 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 or jatos.abortStudy.

    + \ No newline at end of file diff --git a/3.6.x/OSWeb-and-JATOS.html b/3.6.x/OSWeb-and-JATOS.html index 9632ae218..8a69a50cb 100644 --- a/3.6.x/OSWeb-and-JATOS.html +++ b/3.6.x/OSWeb-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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, since JATOS v3.5.1).

    If you'd like to know more

    - +
    Skip to main content
    Version: 3.6.x and earlier

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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, since JATOS v3.5.1).

    If you'd like to know more

    + \ No newline at end of file diff --git a/3.6.x/Papers-Citing-JATOS.html b/3.6.x/Papers-Citing-JATOS.html index 8e170e831..cffc4de10 100644 --- a/3.6.x/Papers-Citing-JATOS.html +++ b/3.6.x/Papers-Citing-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Papers citing JATOS

    JATOS has been used sucessfully to collect data all over the world. Here is a curated list of peer-reviewed publications or preprints (that we are aware of) that used JATOS to collect data. (You can also see the full list of citations.)

    Please cite us 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 on how (much) you use JATOS (ca. 3 min). It’s very important for us!

    2022​

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition. 218. 104945. DOI.

    2021​

    Del Popolo Cristaldi, F., Buodo, G., Gambarota, F., Oosterwijk, S., & Mento, G. (2021, December 16). The role of implicit learning and cue ambiguity on the subjective experience of affective predictions: a follow-up behavioral investigation. PsyArXiv DOI

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Del Popolo Cristaldi, F., Gambarota, F., & Oosterwijk, S. (2021). The role of previous visual experience in subjective reactions to new affective pictures and sounds. PsyArXiv DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    da Fonseca, M., Maffei, G., Matic, A., Bote, R. M., & Hyafil, A. (2021, August 6). Emotional states and self-confidence independently fluctuate at different time scales. PsyArXiv DOI

    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

    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.

    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.

    Lacassagne, D., Béna, J., Corneille, O. (2021). Is Earth a Perfect Square? Repetition Increases the Perceived Truth of Highly Implausible Statements. PsyArxiv. DOI.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    Román-Caballero, R., Marotta, A., Lupiáñez, J. (2021) Spatial Interference Triggered by Gaze and Arrows. Spatial interference from arrows disappears when they are surrounded by an irrelevant context. PsyArXiv; DOI

    Ciston, AB., Forster, C., Brick, TR., Kühn, S., Verrel, J., Filevich, E. (2021) Limited metacognitive access to one's own facial expressions. bioRxiv 2021.03.08.434069; DOI

    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

    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

    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

    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

    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

    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.

    Kumbhar, O., Sizikova, E., Majaj, N., & Pelli, D. G. (2020). Anytime Prediction as a Model of Human Reaction Time. ArXiv2011.12859(Cs, q-Bio). DOI

    Vari, J. & Tamburelli, M. (2020) Standardisation: bolstering positive attitudes towards endangered language varieties? Evidence from implicit attitudes. Journal of Multilingual and Multicultural Development. DOI

    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

    Gorin, S. (2020) Temporal grouping effects in tone sequence reconstruction: testing domain-general positional theories of serial order. PsyArXiv DOI

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Papers citing JATOS

    JATOS has been used sucessfully to collect data all over the world. Here is a curated list of peer-reviewed publications or preprints (that we are aware of) that used JATOS to collect data. (You can also see the full list of citations.)

    Please cite us 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 on how (much) you use JATOS (ca. 3 min). It’s very important for us!

    2022​

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition. 218. 104945. DOI.

    2021​

    Del Popolo Cristaldi, F., Buodo, G., Gambarota, F., Oosterwijk, S., & Mento, G. (2021, December 16). The role of implicit learning and cue ambiguity on the subjective experience of affective predictions: a follow-up behavioral investigation. PsyArXiv DOI

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Del Popolo Cristaldi, F., Gambarota, F., & Oosterwijk, S. (2021). The role of previous visual experience in subjective reactions to new affective pictures and sounds. PsyArXiv DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    da Fonseca, M., Maffei, G., Matic, A., Bote, R. M., & Hyafil, A. (2021, August 6). Emotional states and self-confidence independently fluctuate at different time scales. PsyArXiv DOI

    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

    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.

    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.

    Lacassagne, D., Béna, J., Corneille, O. (2021). Is Earth a Perfect Square? Repetition Increases the Perceived Truth of Highly Implausible Statements. PsyArxiv. DOI.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    Román-Caballero, R., Marotta, A., Lupiáñez, J. (2021) Spatial Interference Triggered by Gaze and Arrows. Spatial interference from arrows disappears when they are surrounded by an irrelevant context. PsyArXiv; DOI

    Ciston, AB., Forster, C., Brick, TR., Kühn, S., Verrel, J., Filevich, E. (2021) Limited metacognitive access to one's own facial expressions. bioRxiv 2021.03.08.434069; DOI

    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

    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

    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

    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

    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

    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.

    Kumbhar, O., Sizikova, E., Majaj, N., & Pelli, D. G. (2020). Anytime Prediction as a Model of Human Reaction Time. ArXiv2011.12859(Cs, q-Bio). DOI

    Vari, J. & Tamburelli, M. (2020) Standardisation: bolstering positive attitudes towards endangered language varieties? Evidence from implicit attitudes. Journal of Multilingual and Multicultural Development. DOI

    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

    Gorin, S. (2020) Temporal grouping effects in tone sequence reconstruction: testing domain-general positional theories of serial order. PsyArXiv DOI

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    + \ No newline at end of file diff --git a/3.6.x/Restricting-study-flow.html b/3.6.x/Restricting-study-flow.html index dea79dd38..8da1b1f16 100644 --- a/3.6.x/Restricting-study-flow.html +++ b/3.6.x/Restricting-study-flow.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Restricting study flow - reloading, linear studies, single-use workers and previews

    Intro: Restricting study flow​

    Let's first say what we understand under the study flow:

    Study flow - the intended order of a study's componenents 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

    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 (since version 3.5.1)​

    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

    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 worker 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 workers: Personal Single worker, General Single worker, and the MTurk worker.

    Remember that General Single links can be used to run a study only once from each browser and each computer, in principle. But if a participant clears their browser cookies, changes browser or sits in front of another computer, they will be able to run the study again.

    Read more on the different worker types available in JATOS

    Perhaps you want to allow General Single or Personal Single workers to have a peek into the study, to preview it, despite restricting them to run the whole study only once. In JATOS you can let these two worker types preview the first component of your study (where you could describe what they will have to do, how long it will take, ask for consent, etc). Often, workers see this description and decide that they want to do the study later.

    To allow them to do this, activate the checkbox Allow preview (this will add a &pre to the end of the URL).

    GUI Screenshot

    Now your workers can use the link as many times as they want - as long as they don't go further than the first component. But once the second component is started, JATOS will restrict access to the study in the usual way as it is for General Single and Personal Single workers. This means that they will get an error if they try to use the link again to access the study.

    If the Allow preview box is unchecked, JATOS will follow its default behaviour: once a worker clicked on the link - that's it, the study is started and JATOS will not allow a second click on this link.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Restricting study flow - reloading, linear studies, single-use workers and previews

    Intro: Restricting study flow​

    Let's first say what we understand under the study flow:

    Study flow - the intended order of a study's componenents 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

    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 (since version 3.5.1)​

    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

    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 worker 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 workers: Personal Single worker, General Single worker, and the MTurk worker.

    Remember that General Single links can be used to run a study only once from each browser and each computer, in principle. But if a participant clears their browser cookies, changes browser or sits in front of another computer, they will be able to run the study again.

    Read more on the different worker types available in JATOS

    Perhaps you want to allow General Single or Personal Single workers to have a peek into the study, to preview it, despite restricting them to run the whole study only once. In JATOS you can let these two worker types preview the first component of your study (where you could describe what they will have to do, how long it will take, ask for consent, etc). Often, workers see this description and decide that they want to do the study later.

    To allow them to do this, activate the checkbox Allow preview (this will add a &pre to the end of the URL).

    GUI Screenshot

    Now your workers can use the link as many times as they want - as long as they don't go further than the first component. But once the second component is started, JATOS will restrict access to the study in the usual way as it is for General Single and Personal Single workers. This means that they will get an error if they try to use the link again to access the study.

    If the Allow preview box is unchecked, JATOS will follow its default behaviour: once a worker clicked on the link - that's it, the study is started and JATOS will not allow a second click on this link.

    + \ No newline at end of file diff --git a/3.6.x/Run-an-experiment-with-JATOS-Workflow.html b/3.6.x/Run-an-experiment-with-JATOS-Workflow.html index 8991a017a..6b4191463 100644 --- a/3.6.x/Run-an-experiment-with-JATOS-Workflow.html +++ b/3.6.x/Run-an-experiment-with-JATOS-Workflow.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Run an experiment with JATOS - Workflow

    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

    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. -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

    Step 2: Deploy files to a server (Make your study available to the WWW)​

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Step 3: Collect data​

    See how to use the Worker and Batch Manager to create links to distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. Use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    - +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

    Step 2: Deploy files to a server (Make your study available to the WWW)​

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Step 3: Collect data​

    See how to use the Worker and Batch Manager to create links to distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. Use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    + \ No newline at end of file diff --git a/3.6.x/Run-your-Study-with-Worker-and-Batch-Manager.html b/3.6.x/Run-your-Study-with-Worker-and-Batch-Manager.html index 355877268..ab2d756dc 100644 --- a/3.6.x/Run-your-Study-with-Worker-and-Batch-Manager.html +++ b/3.6.x/Run-your-Study-with-Worker-and-Batch-Manager.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Run your Study with Worker & Batch Manager

    Worker & Batch Manager​

    The Worker & Batch Manager is the place where you generate links for your particpants to run the your study, organize them into Batches and handle their results.

    Worker &amp; Batch manager screenshot

    This is a screenshot of JATOS v3.3.1. In earlier versions it was called Batch Manager and looked a bit simpler. Each row represents a batch which in turn is a collection of workers.

    How to let participants run your study: Workers​

    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 links that you can hand out to your workers (e.g. via email or social media).

    Generate links and hand them to your workers

    JATOS has different worker types (each with different properties). That's well explained in a dedicated page: Worker Types.

    Click on the "" button in the left in each batch row to expand the Worker Setup.

    Worker Setup​

    Worker Setup

    Screenshot of a Worker & Batch Mangager with an open Worker Setup for the second batch. In JATOS version < 3.3.1 it is reachable via the "Worker Setup" button.

    The Worker Setup is the place where you generate or view (for Jatos and MTurk workers) the links for all workers types.

    For Personal Single Workers and Personal Multiple Workers click "Get Links " ("Add" in older versions). You can enter a description or identification for the worker in the 'Comments' box. You can also create several at once.

    General Single Workers only have one link. Each time somebody clicks on the link, JATOS will create a new separate worker. Get this link by clicking on "Get Link " in its row.

    How to connect to MTurk and create links to run with MTurk Workers is described in its own page: Connect to Mechanical Turk.

    Alternatively there is a "Get Worker Links " button in the top of the Worker & Batch Manger page that is a shortcut to create those links.

    See Workers​

    Click on the "" button in the left in each worker type row to expand it and see all generated workers. The column "Study State" indicates in which state this study run currently is.

    Worker Table

    Screenshot with expanded Personal Single Worker

    Another way to see your workers is the button "All Workers" in the top of the Worker & Batch Manager page.

    All Workers Table

    Screenshot of All Workers table: Here one can search and filter through all workers of all batches and all types that belong to this study.

    How to organize your workers: Batches​

    A batch is a collection of workers together with some properties. 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 Worker & Batch Manager. 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.

    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​

    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.

    Worker &amp; Batch manager screenshot

    Additionally you can switch on or off worker types in the Allowed Worker Types. Unchecked worker types are not allowed to run a study. Always check before you send out links to study runs that the corresponding worker types are switched on.

    The Group Properties relate to group studies.

    Groups (since v3.3.1)​

    A batch is also the place where JATOS groups 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

    Screenshot of a Groups table (available JATOS >= 3.3.1): "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.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Run your Study with Worker & Batch Manager

    Worker & Batch Manager​

    The Worker & Batch Manager is the place where you generate links for your particpants to run the your study, organize them into Batches and handle their results.

    Worker &amp; Batch manager screenshot

    This is a screenshot of JATOS v3.3.1. In earlier versions it was called Batch Manager and looked a bit simpler. Each row represents a batch which in turn is a collection of workers.

    How to let participants run your study: Workers​

    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 links that you can hand out to your workers (e.g. via email or social media).

    Generate links and hand them to your workers

    JATOS has different worker types (each with different properties). That's well explained in a dedicated page: Worker Types.

    Click on the "" button in the left in each batch row to expand the Worker Setup.

    Worker Setup​

    Worker Setup

    Screenshot of a Worker & Batch Mangager with an open Worker Setup for the second batch. In JATOS version < 3.3.1 it is reachable via the "Worker Setup" button.

    The Worker Setup is the place where you generate or view (for Jatos and MTurk workers) the links for all workers types.

    For Personal Single Workers and Personal Multiple Workers click "Get Links " ("Add" in older versions). You can enter a description or identification for the worker in the 'Comments' box. You can also create several at once.

    General Single Workers only have one link. Each time somebody clicks on the link, JATOS will create a new separate worker. Get this link by clicking on "Get Link " in its row.

    How to connect to MTurk and create links to run with MTurk Workers is described in its own page: Connect to Mechanical Turk.

    Alternatively there is a "Get Worker Links " button in the top of the Worker & Batch Manger page that is a shortcut to create those links.

    See Workers​

    Click on the "" button in the left in each worker type row to expand it and see all generated workers. The column "Study State" indicates in which state this study run currently is.

    Worker Table

    Screenshot with expanded Personal Single Worker

    Another way to see your workers is the button "All Workers" in the top of the Worker & Batch Manager page.

    All Workers Table

    Screenshot of All Workers table: Here one can search and filter through all workers of all batches and all types that belong to this study.

    How to organize your workers: Batches​

    A batch is a collection of workers together with some properties. 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 Worker & Batch Manager. 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.

    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​

    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.

    Worker &amp; Batch manager screenshot

    Additionally you can switch on or off worker types in the Allowed Worker Types. Unchecked worker types are not allowed to run a study. Always check before you send out links to study runs that the corresponding worker types are switched on.

    The Group Properties relate to group studies.

    Groups (since v3.3.1)​

    A batch is also the place where JATOS groups 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

    Screenshot of a Groups table (available JATOS >= 3.3.1): "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.

    + \ No newline at end of file diff --git a/3.6.x/Session-Data-Three-Types.html b/3.6.x/Session-Data-Three-Types.html index a27fb193f..4c82c71c3 100644 --- a/3.6.x/Session-Data-Three-Types.html +++ b/3.6.x/Session-Data-Three-Types.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Session Data - Three Types

    When to use the sessions?​

    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 JSON Input Data instead.


    Comparative Overview​

    Batch Session    Group Session    Study Session
    Scope (accesible by)All workers in a batchAll workers in a groupAll components in a study
    UsageExchange and store data relevant for all members of a batchExchange and temporarily store data relevant for all members of a groupExchange 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 batchStore choices of the two members of a Prisoner's Dilemma gamePass on correct answers between components; Keep track of the number of iterations of a given component that is repeated
    LifetimeSurvives after all workers finished their studiesAutomatically deleted once the group is finishedDeleted once the worker finished the study - Hence temporary
    Updated when and viaAny time you call one of the jatos.batchSession functionsAny time you call one of the jatos.groupSession functionsAt the end of each component or if you call jatos.setStudySessionData
    Visible and editable from JATOS' GUIyesnono
    Requires WebSocketsyesyesno
    Included in exported studiesnonono

    Example Study​

    We have an example study, 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".

    2. Run the study once: easiest is as a JATOS worker (just click 'Run' on the study bar, not on any of the component bars).

    3. 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

    4. 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 worker type you want. Additional runs with the JATOS worker will work but you can also use other worker types.

      Second component screenshot

    5. 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. 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 -Second component screenshot

    - +Second component screenshot

    + \ No newline at end of file diff --git a/3.6.x/Study-Log.html b/3.6.x/Study-Log.html index dd0b854b7..3ab46e16d 100644 --- a/3.6.x/Study-Log.html +++ b/3.6.x/Study-Log.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Study Log

    From version 3.2.1 onwards JATOS stores a log file for each study (not to be confused with JATOS' log). 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

    Then the log looks similar to this:

    Study Log pretty

    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 (10.000 JATOS >= v3.4.1) 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, save result data, upload result file
    • In case of saving result data 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 (in the one below).

    Study Log raw

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Study Log

    From version 3.2.1 onwards JATOS stores a log file for each study (not to be confused with JATOS' log). 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

    Then the log looks similar to this:

    Study Log pretty

    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 (10.000 JATOS >= v3.4.1) 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, save result data, upload result file
    • In case of saving result data 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 (in the one below).

    Study Log raw

    + \ No newline at end of file diff --git a/3.6.x/Submit-and-upload-data-to-the-server.html b/3.6.x/Submit-and-upload-data-to-the-server.html index b7899359b..748bf0aab 100644 --- a/3.6.x/Submit-and-upload-data-to-the-server.html +++ b/3.6.x/Submit-and-upload-data-to-the-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Submit and upload data to the server

    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 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 and jatos.appendResultData (available since version 3.1.7) 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect). The latter one exists only since JATOS version 3.5.1 (prior versions can use jatos.endStudyAjax).

    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 (Since JATOS version 3.5.1)​

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Submit and upload data to the server

    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 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 and jatos.appendResultData (available since version 3.1.7) 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect). The latter one exists only since JATOS version 3.5.1 (prior versions can use jatos.endStudyAjax).

    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 (Since JATOS version 3.5.1)​

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    + \ No newline at end of file diff --git a/3.6.x/Tips-and-Tricks.html b/3.6.x/Tips-and-Tricks.html index 94407101d..a4132c0cb 100644 --- a/3.6.x/Tips-and-Tricks.html +++ b/3.6.x/Tips-and-Tricks.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Tips & Tricks

    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​

    You should always test your study before posting it anywhere. Testing that your study runs via a simple link is easy: just generate the link, start the study and run once through it. -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. JATOS offers a way to emulate MTurk, without having to set up anything in the sandbox. Here's how.

    If you think about it, MTurk simply calls a JATOS URL. The URL to start a study is normally http://your-jatos-server/publix/study-id/start (where study-id is a placeholder for the ID of the study you want to run). Two additional variables in the URL's query string tell JATOS that this request comes from MTurk (and that it should display the confirmation code when the study is over): workerId and assignmentId. Both pieces of information are normally generated by MTurk; but they can be any arbitrary string. The only constraint is that the workerId does not already exist within JATOS. (Think of it this way: Because a MTurk worker can run a study only once, the same workerId can be used only once in JATOS.)

    Here are some concrete 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/4/start?batchId=2&workerId=123456&assignmentId=abcdef

    You can use any arbitrary value in the query strings workerId and assignmentId (in this example, workerId = 12345 and assignmentId = abcdef).

    To imitate a run from MTurk's Sandbox additionally set turkSubmitTo to the value 'sandbox':

    http://localhost:9000/publix/4/start?batchId=2&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.

    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.

    Continue an abandoned study​

    Sometimes workers leave in the middle of a study. Maybe their internet connection was down, maybe they just left for the next pub and closed the browser tab. Suppose they now want to continue from where they left it. Using the initial run link will not do what they want: it will either start a new study run, or give an error message, depending on the worker type.

    But there is a way (you'll need to send the worker a new link).

    You'll need three IDs: 1) study ID, 2) component ID of the component from where to restart, and 3) the study result ID. All three IDs are quite easy to get from JATOS' GUI. The component ID can be found in the component table of the study. The study result ID is shown in the study result table. The study ID is part of the URL of every study view, e.g. if the URL of the study view is https://cortex.jatos.org/jatos/19 then the study ID is 19.

    Then the worker who abandoned the study can continue it with the link: https://my-domain-name/publix/<study ID>/\<component ID>/start?srid=\<study result ID>.

    E.g.

    • study ID: 31

    • component ID: 167

    • study result ID: 816

    • domain name and protocol is https://cortex.jatos.org

      Then the URL is: https://cortex.jatos.org/publix/31/167/start?srid=816

    But there is a catch! This works only under three conditions:

    1. the component is set to 'reloadable'
    2. the worker uses the same browser on the same computer and didn't delete JATOS' cookies
    3. the worker didn't start more than 10 JATOS studies at the same time in parallel after running the abandoned study

    Condition 3 is very unlikely a problem and for 1 you can just check the 'reloadable' checkbox in the component's settings. Condition 2 is more difficult, it demands the worker to return to the computer and browser they run the study before.

    Abort study and keep a message​

    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 -even if they cancelled the study-. So you need a way to delete the result data but keep their email.

    To do this, you can send a message together with jatos.abortStudy as a parameter. This message won't be deleted together with the other result data. E.g. jatos.abortStudy("participants ID is 12345678");. This message can then be seen in every Study Result page in the 'Message' column.

    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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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.

    Solution: You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    If your study has only one component (like it is common with OpenSesame/OSWeb or lab.js studies) then you can add an additional component in front of the actual experiment. This component would be a preview component in which you can give an intro to your experiment and most importantly tell your participants that by going on (e.g. clicking on the 'continue' button) they would start the experiment and this can be done only once. One can combine this with a consent form.

    - +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. JATOS offers a way to emulate MTurk, without having to set up anything in the sandbox. Here's how.

    If you think about it, MTurk simply calls a JATOS URL. The URL to start a study is normally http://your-jatos-server/publix/study-id/start (where study-id is a placeholder for the ID of the study you want to run). Two additional variables in the URL's query string tell JATOS that this request comes from MTurk (and that it should display the confirmation code when the study is over): workerId and assignmentId. Both pieces of information are normally generated by MTurk; but they can be any arbitrary string. The only constraint is that the workerId does not already exist within JATOS. (Think of it this way: Because a MTurk worker can run a study only once, the same workerId can be used only once in JATOS.)

    Here are some concrete 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/4/start?batchId=2&workerId=123456&assignmentId=abcdef

    You can use any arbitrary value in the query strings workerId and assignmentId (in this example, workerId = 12345 and assignmentId = abcdef).

    To imitate a run from MTurk's Sandbox additionally set turkSubmitTo to the value 'sandbox':

    http://localhost:9000/publix/4/start?batchId=2&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.

    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.

    Continue an abandoned study​

    Sometimes workers leave in the middle of a study. Maybe their internet connection was down, maybe they just left for the next pub and closed the browser tab. Suppose they now want to continue from where they left it. Using the initial run link will not do what they want: it will either start a new study run, or give an error message, depending on the worker type.

    But there is a way (you'll need to send the worker a new link).

    You'll need three IDs: 1) study ID, 2) component ID of the component from where to restart, and 3) the study result ID. All three IDs are quite easy to get from JATOS' GUI. The component ID can be found in the component table of the study. The study result ID is shown in the study result table. The study ID is part of the URL of every study view, e.g. if the URL of the study view is https://cortex.jatos.org/jatos/19 then the study ID is 19.

    Then the worker who abandoned the study can continue it with the link: https://my-domain-name/publix/<study ID>/\<component ID>/start?srid=\<study result ID>.

    E.g.

    But there is a catch! This works only under three conditions:

    1. the component is set to 'reloadable'
    2. the worker uses the same browser on the same computer and didn't delete JATOS' cookies
    3. the worker didn't start more than 10 JATOS studies at the same time in parallel after running the abandoned study

    Condition 3 is very unlikely a problem and for 1 you can just check the 'reloadable' checkbox in the component's settings. Condition 2 is more difficult, it demands the worker to return to the computer and browser they run the study before.

    Abort study and keep a message​

    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 -even if they cancelled the study-. So you need a way to delete the result data but keep their email.

    To do this, you can send a message together with jatos.abortStudy as a parameter. This message won't be deleted together with the other result data. E.g. jatos.abortStudy("participants ID is 12345678");. This message can then be seen in every Study Result page in the 'Message' column.

    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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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.

    Solution: You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    If your study has only one component (like it is common with OpenSesame/OSWeb or lab.js studies) then you can add an additional component in front of the actual experiment. This component would be a preview component in which you can give an intro to your experiment and most importantly tell your participants that by going on (e.g. clicking on the 'continue' button) they would start the experiment and this can be done only once. One can combine this with a consent form.

    + \ No newline at end of file diff --git a/3.6.x/Troubleshooting.html b/3.6.x/Troubleshooting.html index cfc41d7ee..9fbb438c1 100644 --- a/3.6.x/Troubleshooting.html +++ b/3.6.x/Troubleshooting.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Troubleshooting

    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' (in older version the test page is under '/jatos/test', e.g. for a local installation: localhost:9000/jatos/test).

    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 to prevent Safari's automatic unzip.

    JATOS fails to start?​

    (Or, if you are running Windows, do you get the message 'JATOS is already running. Press any key to continue'...)

    This will happen if your computer crashed before you had the chance to close JATOS.

    This is what you might see on a Mac Terminal if JATOS doesn't start:

    jatos doesn&#39;t start

    Close any open command prompt windows. Then look into your JATOS folder, and check if there's a file called RUNNING_PID. Delete this file and try to start JATOS again.

    Here is how it should look if JATOS started successfully:

    jatos doesn&#39;t start

    Read log file 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 file (not to be confused with the study log) to try to find what the problem might be.

    The standard way to read the log file is directly on the server. You'll find your complete log files in jatos_directory/logs/application.log. Because JATOS is designed to avoid the command line interface, we offer a way to view your log file directly in your browser.

    For security reasons, you must be logged in as a user with admin rights.

    From version 3.6.1 on you can see and download all log files in the Administration page.

    In older versions you can only see today's log file: open the URL http://your-jatos-server/jatos/log. For example, if you're running JATOS locally with the standard settings:

    http://localhost:9000/jatos/log

    A file (library, image, ...) included in the HTML fails to load?​

    There is a common mistake Windows users make that might prevent files in the HTML from loading: Any URL or file path in a HTML file should only use '/' as a file path separator - even on Windows systems. So it should always be e.g. <script src="/study_assets/mystudy/jsPsych-5.0.3/myscript.js"></script> and not <script src="\study_assets\mystudy\jsPsych-5.0.3\myscript.js"></script>. And since version 3.2.3 you can leave out the path's first part and just write <script src="myscript.js"></script>.

    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 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 X terminal or close the window on Windows) before moving it.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Troubleshooting

    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' (in older version the test page is under '/jatos/test', e.g. for a local installation: localhost:9000/jatos/test).

    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 to prevent Safari's automatic unzip.

    JATOS fails to start?​

    (Or, if you are running Windows, do you get the message 'JATOS is already running. Press any key to continue'...)

    This will happen if your computer crashed before you had the chance to close JATOS.

    This is what you might see on a Mac Terminal if JATOS doesn't start:

    jatos doesn&#39;t start

    Close any open command prompt windows. Then look into your JATOS folder, and check if there's a file called RUNNING_PID. Delete this file and try to start JATOS again.

    Here is how it should look if JATOS started successfully:

    jatos doesn&#39;t start

    Read log file 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 file (not to be confused with the study log) to try to find what the problem might be.

    The standard way to read the log file is directly on the server. You'll find your complete log files in jatos_directory/logs/application.log. Because JATOS is designed to avoid the command line interface, we offer a way to view your log file directly in your browser.

    For security reasons, you must be logged in as a user with admin rights.

    From version 3.6.1 on you can see and download all log files in the Administration page.

    In older versions you can only see today's log file: open the URL http://your-jatos-server/jatos/log. For example, if you're running JATOS locally with the standard settings:

    http://localhost:9000/jatos/log

    A file (library, image, ...) included in the HTML fails to load?​

    There is a common mistake Windows users make that might prevent files in the HTML from loading: Any URL or file path in a HTML file should only use '/' as a file path separator - even on Windows systems. So it should always be e.g. <script src="/study_assets/mystudy/jsPsych-5.0.3/myscript.js"></script> and not <script src="\study_assets\mystudy\jsPsych-5.0.3\myscript.js"></script>. And since version 3.2.3 you can leave out the path's first part and just write <script src="myscript.js"></script>.

    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 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 X terminal or close the window on Windows) before moving it.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    + \ No newline at end of file diff --git a/3.6.x/Update-JATOS.html b/3.6.x/Update-JATOS.html index ec9c89f68..4c009116b 100644 --- a/3.6.x/Update-JATOS.html +++ b/3.6.x/Update-JATOS.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Update JATOS

    If you want to update a JATOS server please read this page first.

    We'll periodically update JATOS with new features and bug fixes. We recommend you stay up to date with the latest release. However if you are currently running a study it's always safest to keep the same JATOS version throughout the whole experiment.

    Since version 3.3.5 you can update your JATOS automatically (if you have admin rights and running on Mac OS or Linux (including Docker), that is). Windows is not yet supported.

    Normal process​

    The process is pretty self-explanatory, but anyway, we'll explain it here in detail:

    1. If your JATOS version is not the latest one available, you will get a notification on your JATOS' Administration page (or in your JATOS' home page in older versions).

      Update notification Schreenshot

    2. We expect no problems, but sh&t happens. We recommend that you back up your result data, result files, study assets folder and study logs before continuing.

    3. 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. Usually the variant downloaded will be the one without bundled Java. Only in cases where JATOS switches to a newer version of Java a bundled version is required (see below). The download might take a while depending on your internet connection.

    4. After download is complete, you will be asked again for confirmation. By default, JATOS will back up: it will copy the content of its own installation folder into a folder with the name backup_x.x.x (x.x.x is the version before the update). This will usually include your embedded H2 database, your study assets and logs - but not your MySQL database (should you have one). If anything goes wrong in the auto-update, you have everything in this backup folder to start the old JATOS again. This backup will use up disk space (therefore you can opt out).

      Update notification Schreenshot

    5. After clicking the Go on button, JATOS will stop itself, replace its program files and re-start itself again. This might take up to a minute.

    6. Refresh your JATOS home page every now and then until you see your updated JATOS' login screen again.

    7. Check the new JATOS with the build-in tests: go to Administration ⇒ Tests and check that all tests are 'OK' (in older version the test page is under '/jatos/test', e.g. for a local installation: localhost:9000/jatos/test).

    Special cases​

    Pre-releases (experimental)​

    Pre-releases will not be available as auto-updates by default. If you want to force this to be the case (and you know what you're doing), append the parameter allowPreReleases to your JATOS home page URL (e.g. localhost/jatos?allowPreReleases).

    Enforce an update to a specified version (experimental)​

    The parameter version can be added to your JATOS home page URL (e.g. localhost/jatos?version=v3.6.1) and takes the version tag as specified in GitHub and enforces an update to this version. This should never be used on a JATOS server that stores any valuable data.

    Major updates​

    Auto-updating might not always be possible. JATOS versions will be flagged so that they are not available for auto-update. You'll have to do a manual update.

    Versions with newer Java required​

    Since version 3.4.1 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 wich 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​

    Updating a local installation of JATOS​

    (The procedure is different if you want to update JATOS on a server installation)

    To be absolutely safe you can install the new JATOS version and keep the old one untouched. This way you can switch back if something fails. Just remember that only one JATOS can run at the same time. Always stop your old JATOS instance before starting another one.

    After updating you can Check the new JATOS with the build-in tests: go to Administration ⇒ Tests and check that all tests are 'OK' (in older version the test page is under '/jatos/test', e.g. for a local installation: localhost:9000/jatos/test).

    You can update your local JATOS instance in two main ways:

    First, easy way: discarding your result data​

    If you don't care about result data stored in JATOS:

    1. Export any studies you wish to keep from the old JATOS installation.
    2. Download and install the new version as if it were a new fresh download. Don't start it yet.
    3. Stop the old JATOS and start the new JATOS.
    4. 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
    2. All your studies' and components' properties
    3. The properties of the first (Default) batch

    What will be lost:

    1. All result data will be lost
    2. All workers in all batches (including Default batch)
    3. All batches other than the Default batch
    4. All study logs

    Second way: keeping everything (including your result data)​

    If you do want to keep your studies, batches, and your result data you'll have to move them to the new JATOS.

    1. Stop JATOS (on Unix systems, type $ ./loader.sh stop on the terminal. On Windows MS, close your command window)
    2. Go to the folder of your old JATOS installation. From there copy your assets root folder to the new JATOS installation (Note: By default your assets root folder is called study_assets_root and lays in the JATOS folder but you might have changed this. You can find the location and name in conf/production.conf. It is specified in the line beginning with jatos.studyAssetsRootPath=.)
    3. Go to the folder of your old JATOS installation. From there copy your folder of your uploaded result files to the new JATOS installation (Note: By default this folder is called result_uploads and lays in the JATOS folder but you might have changed this. You can find the location and name in conf/production.conf. It is specified in the line beginning with jatos.resultUploads.path=.)
    4. From the folder of your old JATOS installation copy the folders database and study_logs to the folder of the new JATOS installation.
    5. If you had changed the conf/production.conf file in your old JATOS instance (for example to set a custom location for your study_assets_root folder) you'll have to do this again in the new JATOS version. We recommend re-editing the new version of the file, rather than just overwriting the new with the old version, in case anything in the production.conf file has changed.
    6. Start the new JATOS (on Unix systems, type $ ./loader.sh start on the terminal. On Windows double click the loader.bat)
    7. Open JATOS' test page in a browser /jatos/test and test that everything is OK

    What will be transferred:

    1. Files and subfolders in study assets folder
    2. All your study and components properties
    3. All batches, together with their workers, generated links, and results
    4. All study logs

    What will be lost: -nothing

    - +nothing

    + \ No newline at end of file diff --git a/3.6.x/Updating-a-JATOS-server-installation.html b/3.6.x/Updating-a-JATOS-server-installation.html index 75eab82d9..220f0177c 100644 --- a/3.6.x/Updating-a-JATOS-server-installation.html +++ b/3.6.x/Updating-a-JATOS-server-installation.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Updating a JATOS server installation

    Updating the server instance is equivalent to doing it locally, but make sure that you know what you're doing; especially if you have paired JATOS with a MySQL database.

    Backup your JATOS

    The easiest way to backup is to do a snapshot of the whole server. If you use an external MySQL database with your JATOS, make a backup e.g. using mysqldump -u yourUserName -p yourDatabaseName > yourDatabaseName.out - or a snapshot of the whole database server.

    As with updating of a local JATOS installation you can do it automatically or manually.

    After updating you can check the new JATOS installation with the test page: go to Administration ⇒ Tests and check that all tests are 'OK' (in older version the test page is under '/jatos/test', e.g. for a local installation: localhost:9000/jatos/test).

    This is the easiest way but is only available since JATOS 3.3.5. Then it's the same as in a local installation.

    If you did a manual backup before you don't need to do the backup offered during the update process.

    Manual Update (if automatic doesn't work for you)​

    You have two ways to update manually: 1) Keep your studies but discard all your result data and batches. 2) Keep everything, including your studies and result data (might not always be possible).

    First option: quick and dirty (discarding result data)​

    You can just follow the update instructions for the local installation. If you use a MySQL database don't forget to configure it with a clean and new one (not the one from your old JATOS). Do not use the new JATOS with the old MySQL database unless you choose to keep your data, as described below.

    Second option: keeping everything​

    This means that we have to configure the MySQL database or copy the embedded H2 database files.

    1. Stop the old JATOS using ./loader.sh stop
    2. Copy the new JATOS version to your server, e.g. copy it into the same folder where your old JATOS is located. Don't yet remove the old JATOS instance.
    3. Unzip the new JATOS (unzip jatos-x.x.x-beta.zip)
    4. From the old JATOS installation copy some folders to the new one
      1. Your assets root folder to the new JATOS installation (Note: By default your assets root folder is called study_assets_root and lays in the JATOS folder but you might have changed this.
      2. If exists, your folder for uploaded result files (Note: By default this folder is called result_uploads and lays in the JATOS folder but you might have changed this. This folder exists since version 3.5.1.
      3. If exists, study_logs
    5. Database
      • H2 - If you are using the default H2 database: From your the folder of your old JATOS installation copy the folder database to the new JATOS installation. Remember to stop JATOS before copying the folder.
      • MySQL - For MySQL you don't have to change anything on the database side.
    6. Configure the new JATOS like the old one - usually it's enough to copy the production.conf from the old conf folder into the new one
    7. Start the new JATOS using ./loader.sh start
    8. Open JATOS' test page (Administration ⇒ Tests) and check that everything is 'OK'
    - +
    Skip to main content
    Version: 3.6.x and earlier

    Updating a JATOS server installation

    Updating the server instance is equivalent to doing it locally, but make sure that you know what you're doing; especially if you have paired JATOS with a MySQL database.

    Backup your JATOS

    The easiest way to backup is to do a snapshot of the whole server. If you use an external MySQL database with your JATOS, make a backup e.g. using mysqldump -u yourUserName -p yourDatabaseName > yourDatabaseName.out - or a snapshot of the whole database server.

    As with updating of a local JATOS installation you can do it automatically or manually.

    After updating you can check the new JATOS installation with the test page: go to Administration ⇒ Tests and check that all tests are 'OK' (in older version the test page is under '/jatos/test', e.g. for a local installation: localhost:9000/jatos/test).

    This is the easiest way but is only available since JATOS 3.3.5. Then it's the same as in a local installation.

    If you did a manual backup before you don't need to do the backup offered during the update process.

    Manual Update (if automatic doesn't work for you)​

    You have two ways to update manually: 1) Keep your studies but discard all your result data and batches. 2) Keep everything, including your studies and result data (might not always be possible).

    First option: quick and dirty (discarding result data)​

    You can just follow the update instructions for the local installation. If you use a MySQL database don't forget to configure it with a clean and new one (not the one from your old JATOS). Do not use the new JATOS with the old MySQL database unless you choose to keep your data, as described below.

    Second option: keeping everything​

    This means that we have to configure the MySQL database or copy the embedded H2 database files.

    1. Stop the old JATOS using ./loader.sh stop
    2. Copy the new JATOS version to your server, e.g. copy it into the same folder where your old JATOS is located. Don't yet remove the old JATOS instance.
    3. Unzip the new JATOS (unzip jatos-x.x.x-beta.zip)
    4. From the old JATOS installation copy some folders to the new one
      1. Your assets root folder to the new JATOS installation (Note: By default your assets root folder is called study_assets_root and lays in the JATOS folder but you might have changed this.
      2. If exists, your folder for uploaded result files (Note: By default this folder is called result_uploads and lays in the JATOS folder but you might have changed this. This folder exists since version 3.5.1.
      3. If exists, study_logs
    5. Database
      • H2 - If you are using the default H2 database: From your the folder of your old JATOS installation copy the folder database to the new JATOS installation. Remember to stop JATOS before copying the folder.
      • MySQL - For MySQL you don't have to change anything on the database side.
    6. Configure the new JATOS like the old one - usually it's enough to copy the production.conf from the old conf folder into the new one
    7. Start the new JATOS using ./loader.sh start
    8. Open JATOS' test page (Administration ⇒ Tests) and check that everything is 'OK'
    + \ No newline at end of file diff --git a/3.6.x/Use-Prolific.html b/3.6.x/Use-Prolific.html index ca0d6a1a8..efa2d57b8 100644 --- a/3.6.x/Use-Prolific.html +++ b/3.6.x/Use-Prolific.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Use Prolific

    It is very easy to use JATOS together with Prolific to recruit participants.

    This is what the New Study page in Prolific looks like:

    Prolific screenshot

    In the field under What is the URL of your study? (first red box in the screenshot), enter a link to your JATOS study.You probably want a link to either a General Single or a General Multiple worker type (see JATOS' worker types and Run your Study with Worker & Batch Manager).

    2. (Optional) 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. Click on 'Show advanced' and then 'Add parameters' like in the screenshot.

    Prolific screenshot

    Then you can access those URL parameters in your study's JavaScript via jatos.urlQueryParameters.

    3. Redirect to Prolific's end page after the study is done​

    The second red box contains a link that will (re)direct the participant to a Prolific page, with information on how to claim their payment.

    Choose one of the three ways (differ in JATOS version and your preferences)

    1. Include jatos.endStudyAjax in the JavaScript of your last component (works with all JATOS versions)

      All you need to do is call jatos.endStudyAjax, and add a callback that will replace window.location.href with the Prolific end page once the ajax call is done:

      jatos.endStudyAjax().then(() => {
        // Change this URL to the one you see in Prolific
        window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'
      });

      Of course, this can also be done together with jatos.submitResultData if you want to store result data in JATOS:

      var result = { test: "some results" };
      jatos.submitResultData(result)
        .then(jatos.endStudyAjax)
        .then(() => {
          window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'
      });

      We provide a Prolific example study that you can use as a template.

    2. Setup End Redirect URL in the Study Properties (easiest - but only since JATOS v3.5.1)

      In JATOS GUI you can put the in Prolific link in the End Redirect URL field of your Study Properties

      screenshot

    3. Include jatos.endStudyAndRedirect in the JavaScript of your last component (since JATOS v3.5.1)

      E.g. but change this URL to the one you see in Prolific

      // Change this URL the one you see in Prolific
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

      You can even combine it with sending result data

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    - +
    Skip to main content
    Version: 3.6.x and earlier

    Use Prolific

    It is very easy to use JATOS together with Prolific to recruit participants.

    This is what the New Study page in Prolific looks like:

    Prolific screenshot

    In the field under What is the URL of your study? (first red box in the screenshot), enter a link to your JATOS study.You probably want a link to either a General Single or a General Multiple worker type (see JATOS' worker types and Run your Study with Worker & Batch Manager).

    2. (Optional) 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. Click on 'Show advanced' and then 'Add parameters' like in the screenshot.

    Prolific screenshot

    Then you can access those URL parameters in your study's JavaScript via jatos.urlQueryParameters.

    3. Redirect to Prolific's end page after the study is done​

    The second red box contains a link that will (re)direct the participant to a Prolific page, with information on how to claim their payment.

    Choose one of the three ways (differ in JATOS version and your preferences)

    1. Include jatos.endStudyAjax in the JavaScript of your last component (works with all JATOS versions)

      All you need to do is call jatos.endStudyAjax, and add a callback that will replace window.location.href with the Prolific end page once the ajax call is done:

      jatos.endStudyAjax().then(() => {
        // Change this URL to the one you see in Prolific
        window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'
      });

      Of course, this can also be done together with jatos.submitResultData if you want to store result data in JATOS:

      var result = { test: "some results" };
      jatos.submitResultData(result)
        .then(jatos.endStudyAjax)
        .then(() => {
          window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'
      });

      We provide a Prolific example study that you can use as a template.

    2. Setup End Redirect URL in the Study Properties (easiest - but only since JATOS v3.5.1)

      In JATOS GUI you can put the in Prolific link in the End Redirect URL field of your Study Properties

      screenshot

    3. Include jatos.endStudyAndRedirect in the JavaScript of your last component (since JATOS v3.5.1)

      E.g. but change this URL to the one you see in Prolific

      // Change this URL the one you see in Prolific
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

      You can even combine it with sending result data

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    + \ No newline at end of file diff --git a/3.6.x/User-Manager.html b/3.6.x/User-Manager.html index 2be1cef44..bf454c42b 100644 --- a/3.6.x/User-Manager.html +++ b/3.6.x/User-Manager.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    Manage JATOS users

    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 admin rights, which lets them access the Administration page and control other users' access to JATOS.

    Manage users​

    Only users with admin rights have access to the User Manager (through a menu button located in the header on every GUI page or since v3.6.1 on the Administration page only). From the User Manager, admins can create new users or delete existing ones, or change passwords. Since v3.6.1 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'). 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 either during creation or in the Admin column of the table. Only admins can access the Administration pages (like User Manager or Study Info).

    User manager screenshot

    Since v3.6.1: 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).

    Since v3.6.1: 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

    Since v3.6.1: 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.

    Authentication via LDAP (version >= 3.5.4)​

    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.

    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.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    Manage JATOS users

    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 admin rights, which lets them access the Administration page and control other users' access to JATOS.

    Manage users​

    Only users with admin rights have access to the User Manager (through a menu button located in the header on every GUI page or since v3.6.1 on the Administration page only). From the User Manager, admins can create new users or delete existing ones, or change passwords. Since v3.6.1 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'). 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 either during creation or in the Admin column of the table. Only admins can access the Administration pages (like User Manager or Study Info).

    User manager screenshot

    Since v3.6.1: 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).

    Since v3.6.1: 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

    Since v3.6.1: 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.

    Authentication via LDAP (version >= 3.5.4)​

    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.

    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.

    + \ No newline at end of file diff --git a/3.6.x/Whats-JATOS.html b/3.6.x/Whats-JATOS.html index cbab3ef19..e90e202f1 100644 --- a/3.6.x/Whats-JATOS.html +++ b/3.6.x/Whats-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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 workers, to e.g. make sure that each participant does your study only once.
    • Upload files, e.g. audio or video recordings
    • Export/Import studies to facilitate exchange with other researchers.
    • You can try out JATOS on cortex, our test server.

    Watch an introduction video:



    JATOS is open-source and released under the Apache 2 Licence. The source code is available on github.com/JATOS/JATOS.

    Several studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    Download the latest release

    - +
    Skip to main content
    Version: 3.6.x and earlier

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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 workers, to e.g. make sure that each participant does your study only once.
    • Upload files, e.g. audio or video recordings
    • Export/Import studies to facilitate exchange with other researchers.
    • You can try out JATOS on cortex, our test server.

    Watch an introduction video:



    JATOS is open-source and released under the Apache 2 Licence. The source code is available on github.com/JATOS/JATOS.

    Several studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    Download the latest release

    + \ No newline at end of file diff --git a/3.6.x/Worker-Types.html b/3.6.x/Worker-Types.html index 9bbd7bc55..37035603b 100644 --- a/3.6.x/Worker-Types.html +++ b/3.6.x/Worker-Types.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Worker Types

    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.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral Multiple (since v3.3.2)MTurk (Sandbox)
    Icon
    Typical useDuring study developmentSmall targeted group, each one of them gets a linkSmall targeted group of workers who pilot the study or need to do it multiple timesBigger groups but with less control; link shared e.g. via social mediaBigger groups and where the workers need to do it multiple timesFor Amazon Mechanical Turk
    Created when?Together with the JATOS userWhen you create the linkWhen you create the linkOn-the-fly whenever someone uses the linkOn-the-fly whenever someone uses the linkOn-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
    Possible bulk creation
    Run 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.

    Personal Single Worker​

    With a Personal Single link a study can be run only once (*But see Preview Links). You can think of them as personalized links with single access. Each Personal Single link corresponds a Personal Single worker.

    Usually you would send a Personal Single link to workers that you contact individually. Each link can be personalized with a Comment you provide while creating it (e.g. by providing a pseudonym).

    Personal Single 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. You can create Personal Single links in bulk by changing the Amount value.

    GUI Screenshot -GUI Screenshot

    Personal Multiple Worker​

    With a Personal Multiple link the worker can run a study as many times as they want. Each Personal Multiple link corresponds to a Personal Multiple worker.

    You could send Personal Multiple links to your pilot workers. Each link can be personalized with a Comment you provide while creating it (e.g. by providing a pseudonym). You can create Personal Multiple links in bulk by changing the Amount value.

    General Single Worker​

    This link type can be used many times by different participants to run a study but only once per browser (*But see Preview Links). Each time the link is used a new General Single worker is created on-the-fly.

    You could distribute a General Single link through 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 worker has already accessed a study. If someone uses a different computer, a new browser, or simply deletes their browser's cookies, then JATOS will assume that it's a new worker. So the same person could (with some effort) use a General Single link several times.

    General Multiple Worker (since version 3.3.2)​

    A General Multiple 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 link can be used repeatedly even in the same browser. Each time a General Multiple 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 link in Amazon's Mechanical Turk (AMT).

    DATA PRIVACY NOTE: If the same worker from AMT 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 AMT 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 page for more details on this.

    - +GUI Screenshot

    Personal Multiple Worker​

    With a Personal Multiple link the worker can run a study as many times as they want. Each Personal Multiple link corresponds to a Personal Multiple worker.

    You could send Personal Multiple links to your pilot workers. Each link can be personalized with a Comment you provide while creating it (e.g. by providing a pseudonym). You can create Personal Multiple links in bulk by changing the Amount value.

    General Single Worker​

    This link type can be used many times by different participants to run a study but only once per browser (*But see Preview Links). Each time the link is used a new General Single worker is created on-the-fly.

    You could distribute a General Single link through 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 worker has already accessed a study. If someone uses a different computer, a new browser, or simply deletes their browser's cookies, then JATOS will assume that it's a new worker. So the same person could (with some effort) use a General Single link several times.

    General Multiple Worker (since version 3.3.2)​

    A General Multiple 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 link can be used repeatedly even in the same browser. Each time a General Multiple 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 link in Amazon's Mechanical Turk (AMT).

    DATA PRIVACY NOTE: If the same worker from AMT 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 AMT 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 page for more details on this.

    + \ No newline at end of file diff --git a/3.6.x/Write-Group-Studies-I-Setup.html b/3.6.x/Write-Group-Studies-I-Setup.html index ecfec60b6..6bf448ceb 100644 --- a/3.6.x/Write-Group-Studies-I-Setup.html +++ b/3.6.x/Write-Group-Studies-I-Setup.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Write Group Studies I - Setup

    (If you haven't already, we recommend that you try out some example group studies.)

    Set up group studies​

    First and common to all group setups is to check the Group study checkbox in the study properties. -Group&#39;s property

    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:

    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.
    2. 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.
    3. 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.

    Worker &amp; Batch manager screenshot

    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 define two Personal Single workers and send the access links (displayed in the batch) 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.

    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). Create your 6 workers in the Worker Setup (or use a General Single link) and distribute your link(s) to your workers.

    Prisoners example

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 General Single worker and publish its link (e.g. via a mailing list or on a website). But keep in mind: this way many workers might access your study at the same time and this might overload your JATOS server.

    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.

    Snake example

    (Continue with Write Group Studies II - JavaScript and Messaging)

    - +Group&#39;s property

    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:

    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.
    2. 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.
    3. 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.

    Worker &amp; Batch manager screenshot

    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 define two Personal Single workers and send the access links (displayed in the batch) 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.

    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). Create your 6 workers in the Worker Setup (or use a General Single link) and distribute your link(s) to your workers.

    Prisoners example

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 General Single worker and publish its link (e.g. via a mailing list or on a website). But keep in mind: this way many workers might access your study at the same time and this might overload your JATOS server.

    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.

    Snake example

    (Continue with Write Group Studies II - JavaScript and Messaging)

    + \ No newline at end of file diff --git a/3.6.x/Write-Group-Studies-II-JavaScript-and-Messaging.html b/3.6.x/Write-Group-Studies-II-JavaScript-and-Messaging.html index a174cdceb..2c8a308b3 100644 --- a/3.6.x/Write-Group-Studies-II-JavaScript-and-Messaging.html +++ b/3.6.x/Write-Group-Studies-II-JavaScript-and-Messaging.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Write Group Studies II - JavaScript and Messaging

    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:

    Joining a group and opening group channels​

    There are two requisites for allowing group members to interact:

    1. 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 remain in the same group. This feature makes groups much more robust.

    2. Communication can only be done if a group channel is open. Although jatos.js opens and closes all necessary group channels so you don't have to care for them directly while writing components. Group channels in turn use WebSockets. WebSockets are supported by all modern browsers.

    So here's how a typical JATOS group study run would look like:

    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 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.

    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 Worker & Batch Manger.

    Reassigning to a different group​

    To move a worker from one group to a different one, use jatos.reassignGroup. 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 the 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 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. Alternatively (since JATOS >= v3.4.1) you can fix a group in JATOS' GUI, in the groups table.

    Communication between group members​

    JATOS provides three ways for communicating within the group: direct messaging, broadcast messaging and via the Group Session.

    Direct messaging​

    Members can send direct messages to a single other member of the same group with the jatos.sendGroupMsgTo 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    - +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 remain in the same group. This feature makes groups much more robust.

  • Communication can only be done if a group channel is open. Although jatos.js opens and closes all necessary group channels so you don't have to care for them directly while writing components. Group channels in turn use WebSockets. WebSockets are supported by all modern browsers.

    • So here's how a typical JATOS group study run would look like:

    Component 1

    Component 2

    Component 3

    Notice that by calling jatos.joinGroup 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.

    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 Worker & Batch Manger.

    Reassigning to a different group​

    To move a worker from one group to a different one, use jatos.reassignGroup. 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 the 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 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. Alternatively (since JATOS >= v3.4.1) you can fix a group in JATOS' GUI, in the groups table.

    Communication between group members​

    JATOS provides three ways for communicating within the group: direct messaging, broadcast messaging and via the Group Session.

    Direct messaging​

    Members can send direct messages to a single other member of the same group with the jatos.sendGroupMsgTo 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    + \ No newline at end of file diff --git a/3.6.x/Write-your-own-Study-Basics-and-Beyond.html b/3.6.x/Write-your-own-Study-Basics-and-Beyond.html index 452b61b5c..64fd71295 100644 --- a/3.6.x/Write-your-own-Study-Basics-and-Beyond.html +++ b/3.6.x/Write-your-own-Study-Basics-and-Beyond.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    Write your own Study - Basics and Beyond

    After you created a new study ... what comes next?

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    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 and click on Components -> New.

    New Component

    Then In the following form you define the component's properties: enter 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

    Click on 'Create' and you are done. If you add more than one component you can change the order in which they run by drag-and-drop on the position button.

    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>
        <head>
          <script src="/assets/javascripts/jatos.js"></script>
        </head>
      </html>

      Since JATOS v3.3.1 it can be simply:

      <html>
        <head>
          <script src="jatos.js"></script>
        </head>
      </html>

    2. The second bit is not really necessary but without defining the jatos.onLoad callback function you won't be able to use most 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 untill jatos.js is finished initializing.

      <script>
        jatos.onLoad(function() {
          // Start here with your code that uses jatos.js' variables and functions
        });
      </script>

    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.

    jatos.js Reference​

    In your JavaScript you will use jatos.js to handle everything JATOS related and in its reference every function and field is described in detail.

    Study JSON Input and Component JSON 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 JSON Input or Component JSON Input because both can be easily edited in the Study Properties or Component Properties.

    Study Properties / JSON input

    Both input fields take JSON 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 JSON Input and Component JSON 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 JSON Input

    {
       "introduction": "this is a text",
       "order": [3, 1, 2]
    }

    you can access those fields in your JavaScript with jatos.studyJsonInput.introduction 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.

    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, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    - +To get an idea it's best to start with examples, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    + \ No newline at end of file diff --git a/3.6.x/jatos.js-Reference.html b/3.6.x/jatos.js-Reference.html index d30b1b56c..14604122c 100644 --- a/3.6.x/jatos.js-Reference.html +++ b/3.6.x/jatos.js-Reference.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.6.x and earlier

    jatos.js Reference

    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 the variables and functions of the jatos.js library.

    Always load the jatos.js script in the <head> section with the following line:

    <script src="jatos.js"></script>

    or before version 3.3.1 with:

    <script src="/assets/javascripts/jatos.js"></script>

    All variables or calls to jatos.js start with jatos.. For example, if you want to get the study's ID you use jatos.studyId.

    And, please, if you find a mistake or have a question don't hesitate to contact us.

    jatos.js variables​

    You can call any of these variables below at any point in your HTML file after jatos.js finished initializing (jatos.onLoad() will be called). Most variables are read-only. A few variables can be written into (e.g. jatos.httpTimeout). Those are marked '(writeable)'.

    IDs​

    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.

    • 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.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
    • jatos.groupResultId - see Group Variables

    There's a convenient function that adds all these IDs to a given object. See function jatos.addJatosIds(obj) below.

    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.
    • jatos.studyLength - Number of component this study has

    Original URL query parameters​

    • jatos.urlQueryParameters - Original query string parameters of the URL that starts the study. It is provided as a JavaScript object. 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.

      Example: One has this link to start a Personal Single Run:

      http://localhost:9000/publix/50/start?batchId=47&personalSingleWorkerId=506

      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/50/start?batchId=47&personalSingleWorkerId=506&foo=bar&a=123

      Then those parameter will be accessible during the study run in jatos.urlQueryParameters as {a: "123", foo: "bar"}.

      Example: MTurk uses for its worker ID the URL query parameter 'workerId' and this is accessible via jatos.urlQueryParameters.workerId.

    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.
    • 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)

    Study's session data​

    The session data 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).

    • jatos.studySessionData (writeable)

    Other variables​

    All variables can be set except those labled read-only.

    • jatos.version (read-only) - Current version of the jatos.js library

    • 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).

      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)

      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)

      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)

      jatos.channelClosedCheckInterval = 4000; // Sets interval to 4 seconds

    • jatos.channelOpeningBackoffTimeMin and jatos.channelOpeningBackoffTimeMax - Min and 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.

      jatos.channelOpeningBackoffTimeMin = 2000; // Sets interval to 2 seconds
      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).

      jatos.httpTimeout = 30000; // Sets HTTP timeout to 30 seconds

    • jatos.httpRetry - Some jatos functions (e.g. jatos.sendResultData) send an Ajax 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. 

      jatos.httpRetry = 2; // Attempts 2 retries of failed Ajax requests

    • jatos.httpRetryWait - Same as jatos.httpRetry but this variable defines the waiting time between the retries. The default is 1000 ms.

      jatos.httpRetryWait = 5000; // Sets Ajax retry waiting time to 5 seconds

    • jatos.waitSendDataOverlayConfig - (Since version 3.5.11) - 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.

      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

    jatos.onLoad(function() {
      // Start here with your code that uses jatos.js' variables and functions
    });

    jatos.addAbortButton​

    Since JATOS version >= 3.5.1 - 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 - (since v3.5.11) Which function should be called in the end. Default is jatos.abortStudy.

    Examples

    1. Adds the default cancel button

      jatos.addAbortButton()

    2. Adds a cancel button and changes some properties

      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"
      });

    3. Adds a cancel button and changes the position to the bottom-left

      jatos.addAbortButton({
        style: "left:1em"
      });

    4. Adds a cancel button and calls 'myFunction' if pressed

      jatos.addAbortButton({
        action: myFunction
      });

    jatos.showBeforeUnloadWarning​

    Since JATOS version >= 3.5.6 - 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:

    jatos.showBeforeUnloadWarning(true);

    jatos.showOverlay​

    Since JATOS version >= 3.5.11 - 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.

      jatos.showOverlay()

    2. Shows text only

      jatos.showOverlay({
        text: "Please have a coffee break for 5 minutes",
        showImg: false
      });

    3. Shows text only

      jatos.showOverlay({
        text: "Please have a coffee break for 5 minutes",
        imgUrl: "http://url-to-my-coffee-picture",
        style: "color:brown"
      });

    jatos.removeOverlay​

    Since JATOS version >= 3.5.11 - Removes an overlay that was added by jatos.showOverlay.

    Example

    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:

    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

    jatos.log("Log this message in JATOS' log file");

    jatos.catchAndLogErrors​

    Since JATOS version >= 3.5.6 - Convenience function that sends all 'error' and 'unhandledrejection' events and 'console.error' and 'console.warn' calls to JATOS' server log. This is useful in debugging.

    Example

    jatos.catchAndLogErrors();

    jatos.addJatosIds​

    Convenience function that adds some IDs (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

    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

    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 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, 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

    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. 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. Since v3.3.1 one can additionally send result data back to the JATOS server.

    Since v3.4.1 there are two version: with or without message

    1. Without message:

      • @param {number} componentId - ID of the component to start
      • @param {optional object} resultData - (JATOS >= v3.3.1) 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

    2. With message (since JATOS >= v3.4.1):

      • @param {number} componentId - ID 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

      jatos.startComponent(23);

    2. Since v3.3.1: send result data and jump to another component

      var resultData = "my important result data";
      jatos.startComponent(23, resultData);

    3. Since v3.4.1: send result data, jump to another component and send a message back that will be visible in JATOS result pages and log 

      var resultData = "my important result data";
      jatos.startComponent(23, resultData, "everything okay");

    4. In versions < v3.3.1 it's often used together with jatos.submitResultData to first submit result data back to the JATOS server and afterwards jump to another component

      var resultData = "my important result data";
      jatos.submitResultData(resultData, function() {
        jatos.startComponent(23);
      });

    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, ...). Since v3.3.1 one can additionally send result data back to the JATOS server.

    Since v3.4.1 there are two versions: with or without message

    1. Without message

      • @param {number} componentPos - Position of the component to start
      • @param {optional object} resultData - (JATOS >= v3.3.1) 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

    2. With message (since JATOS >= v3.4.1)

      • @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

      jatos.startComponentByPos(3);

    2. Since v3.3.1: send result data and jump to component with position 3

      var resultData = "my important result data";
      jatos.startComponentByPos(3, resultData);

    3. Since v3.4.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 

      var resultData = "my important result data";
      jatos.startComponentByPos(3, resultData, "everything okay");

    4. In versions < v3.3.1 it's often used together with jatos.submitResultData to first submit result data back to the JATOS server and afterwards jump to component in position 3

      var resultData = "my important result data";
      jatos.submitResultData(resultData, function() {
        jatos.startComponentByPos(3);
      });

    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, ...). Since v3.3.1 one can additionally send result data back to the JATOS server.

    Since v3.4.1 there are two versions: with or without message

    1. Without message

      • @param {optional object} resultData - (JATOS >= v3.3.1) 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

    2. With message (since JATOS >= v3.4.1)

      • @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

      jatos.startNextComponent();

    2. Since v3.3.1: send result data and jump to the next component

      var resultData = "my important result data";
      jatos.startNextComponent(resultData);

    3. Since v3.4.1: send result data, jump to the next component and send a message back that will be visible in JATOS result pages and log 

      var resultData = "my important result data";
      jatos.startNextComponent(resultData, "everything okay");

    4. In versions < v3.3.1 it's often used together with jatos.submitResultData to first submit result data back to the JATOS server and afterwards jump to the next component

      var resultData = "my important result data";
      jatos.submitResultData(resultData, jatos.startNextComponent);

    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, ...). Since v3.3.1 one can additionally send result data back to the JATOS server.

    Since v3.4.1 there are two versions: with or without message

    1. Without message

      • @param {optional object} resultData - (JATOS >= v3.3.1) 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

    2. With message (since JATOS >= v3.4.1)

      • @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

      jatos.startLastComponent();

    2. Since v3.3.1: send result data and jump to the last component

      var resultData = "my important result data";
      jatos.startLastComponent(resultData);

    3. Since v3.4.1: send result data, jump to the last component and send a message back that will be visible in JATOS result pages and log

      var resultData = "my important result data";
      jatos.startLastComponent(resultData, "everything okay");

    1. In versions < v3.3.1 it's often used together with jatos.submitResultData to first submit result data back to the JATOS server and afterwards jump to the last component

      var resultData = "my important result data";
      jatos.submitResultData(resultData, jatos.startLastComponent);

    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 uneffected 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

      jatos.abortStudy();

    2. Additionally send a message

      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 uneffected by this. It offers callbacks, either as parameter or via a 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

      jatos.abortStudyAjax();

    2. Abort study with a message that will be sent back to JATOS and shown in the result page and put in the log

      jatos.abortStudyAjax("Worker clicked Abort button");

    jatos.endStudy​

    Ends study. Redirects the worker to study's end page afterwards.

    Since v3.4.1 there are two versions: with and without result data

    1. With result data (since JATOS >= v3.4.1)

      • @param {optional string or object} resultData - Result data to be sent back to 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

    2. 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

      jatos.endStudy();

    2. End study and send a message back that will be visible in JATOS result pages and log 

      jatos.endStudy(true, "everything worked fine");

    3. Indicate a failure - leads to study result state FAIL

      jatos.endStudy(false, "internal JS error");

    4. Send result data and end study (since JATOS >= v3.4.1)

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudy(resultData);

    5. Send result data, end study and send a message back that will be visible in JATOS result pages and log (since JATOS >= v3.4.1)

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudy(resultData, true, "everything worked fine");

    jatos.endStudyAndRedirect​

    Since JATOS version >= 3.5.1 - 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, 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

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    2. End study and redirect afterwards. Send result data.

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);

    3. End study and redirect afterwards. A message will be sent back to JATOS and shown in the result page and put in the log.

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", true, "everything worked fine");

    4. End study and indicate a failure and send a message. Does not redirect.

      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, 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

      jatos.endStudyAjax();

    2. End study with a message that will be sent back to JATOS and shown in the result page and put in the log

      jatos.endStudyAjax(true, "everything worked fine");

    3. Indicate a failure and send a message

      jatos.endStudyAjax(false, "some error description");

    4. End study and show the confirmation code to the MTurk worker

      jatos.endStudyAjax().then((confirmationCode) => {
        // Show the confirmation code to the worker
      });

    5. Use Promise to submit result data and afterwards, end the study and move to another URL (see also)

      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"));

    6. Send result data and end study (since JATOS >= v3.4.1)

      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, 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

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData);

    2. Since v3.3.1 it's possible to leave out the JSON serialization

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData);

    3. 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

      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)

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData, () => { jatos.startComponentByPos(4) });

    2. Or by using the returned Promise

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData)
         .then(() => console.log('success'))
         .catch(() => console.log('error'));

    jatos.appendResultData​

    Since JATOS version >= 3.1.7 - 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, 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

      var resultData = { "a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData);

    2. Since v3.3.1 it's possible to leave out the JSON serialization

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData);

    3. Use mulitple jatos.appendResultData in a row

      jatos.appendResultData({"a": 1})
         .then(() => jatos.appendResultData({"b": 2}))
         .then(() => jatos.appendResultData({"c": 3}))
         .catch(() => console.log('Something went wrong'));

    4. You can use it together with jatos.startNextComponent to first append result data and afterwards jump to the next component

      var resultData = { "a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData, jatos.startNextComponent);

    5. Or by using the returned Promise

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData)
         .then(() => jatos.startNextComponent())
         .catch(() => console.log('Something went wrong'));

    6. Or together with jatos.startComponentByPos to start a particular component (here at position 4)

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData)
         .then(() => jatos.startComponentByPos(4))
         .catch(() => console.log('Something went wrong'));

    jatos.uploadResultFile​

    Since JATOS version >= 3.5.1 - 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, to signal success or failure in the transfer.

    • @param {Blob, string or object} obj - Data to be uploaded as a file. Can be 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

      jatos.uploadResultFile("this is my data", "example.txt")
         .then(() => console.log("File was successfully uploaded"))
         .catch(() => console.log("File upload failed"));

    2. Upload object as JSON

      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"));

    3. Upload text as Blob

      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"));

    4. Turn canvas into Blob and upload as image file. It assumes you have an canvas element with ID 'canvas'.

      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"));
      });

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    jatos.downloadResultFile​

    Since JATOS version >= 3.5.1 - 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 are returned as a Blob. It offers callbacks, either as parameter or via a 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

      jatos.downloadResultFile("example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    2. Download JSON file

      jatos.downloadResultFile("example.json")
         .then((obj) => console.log(JSON.stringify(obj)))
         .catch(() => console.log("File download failed"));

    3. Download image and display it in a canvas element

      jatos.downloadResultFile("canvas.png")
         .then((blob) => { document.getElementById("canvas").src = URL.createObjectURL(blob) })
         .catch(() => console.log("File download failed"));

    4. Download file and specify that the file was uploaded in the first component

      jatos.downloadResultFile(1, "example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    Batch​

    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 this group can have at the same time
      • jatos.batchProperties.maxTotalMembers - How many members this group is allowed to have at the same time
      • jatos.batchProperties.maxTotalWorkers - Total amount of workers this 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.

    Functions to access the Batch Session​

    The Batch Session is stored in JATOS' database on the server side (see also Session Data - Three Types). 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.

    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) and JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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 (before v3.3.1 one parameter):

    • @param {string} path - JSON pointer to the changed field in the Batch Session
    • @param {string} op - (version >= 3.3.1) JSON patch operation ('add', 'remove', 'clear', ...) that was applied

    Examples

    1. Log whenever something changes in the Batch session

      jatos.onBatchSession(function(path, op){
        console.log("Batch Session was updated in path " + path + " with operation " + op);
      });

    2. onBatchSession is often used together with jatos.batchSession.find to get the updated value:

      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 an field within the Batch Session and returns the matching value. 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"}

      // 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

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.batchSession.set("b", "koala")
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    3. Have a series of Batch Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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. 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}

      jatos.batchSession.find("/a/a1"); // returns "foo"
      jatos.batchSession.find("/b"); // returns 999

    jatos.batchSession.defined​

    Since JATOS version >= 3.1.8 - 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

    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).

    • @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"}}

      jatos.batchSession.test("/a", 123); // returns true
      jatos.batchSession.test("/a", 10); // returns false
      jatos.batchSession.test("/b/b1", "flowers"); // returns true

    2. If you want to know the existence of a path in the Batch Session you can test against undefined:

      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). If the path already exists in the Batch Session the value will be overwritten.

    • @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

      jatos.batchSession.add("/a", 100);

      After the Batch Session is successfully updated the new object is {"a": 100}.

    2. Add to Batch Session

      If the Batch Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or fail

      jatos.batchSession.add("/b", 123)
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add an array:

      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]}.

    6. Add an element to an array:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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]}.

    7. Append to the end of an array using /-:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    8. Have a series of Batch Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      jatos.batchSession.move("/a", "/b")
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    jatos.batchSessionVersioning​

    Since JATOS version >= 3.5.6 - 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

    jatos.batchSessionVersioning = false; // Turns off versioning

    Group studies​

    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.groupState (Removed in JATOS >= v3.4.1) - Represents the state of the group in JATOS; only set if group channel is open (one of STARTED, FIXED, FINISHED)
    • 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

    Functions for group studies​

    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, 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 (before v3.3.1 only one): 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

      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));
      }

    2. Example that defines the onOpen, onMemberOpen, and onMessage callbacks

      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. 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

    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

      var msg = "Message for group member 1063";
      jatos.sendGroupMsgTo("1063", msg)

    2. Use the onMemberOpen callback to send a message right after a new member opened their group channel

      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, 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

    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, 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

    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, 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

    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

    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

    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

    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

    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

    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) and broadcast messaging (jatos.sendGroupMsg) (or: more general information about the different session types).

    In difference to 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). 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.

    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) and -JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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. 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"}

      // 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.

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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. 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}

    jatos.groupSession.find("/a/a1"); // returns "foo"
    jatos.groupSession.find("/b"); // returns 999

    the first line returns "foo" and the second 999.

    jatos.groupSession.defined​

    Since JATOS version >= 3.1.8 - 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

    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).

    • @param {string} path - JSON pointer path to be tested
    • @param {object} value - value to be tested
    • @return {boolean}

    Example

    Given the Group Session is {"a": 123, "b": {"b1": "flowers", "b2": "animals"}}

    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.

    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). If the path already exists in the Group Session the value will be overwritten.

    • @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 Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Example with an array: Put the object {id: 123, name: "Max"} after the second position of the array with the path /subjects:

      jatos.groupSession.add("/subjects/2", {id: 123, name: "Max"})
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Example of how to append to the end of an array: use /- after the arrays name:

      jatos.groupSession.add("/subjects/-", {id: 124, name: "Adam"})
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    5. Have a series of Group Session changes

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.move("/a", "/b")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    jatos.groupSessionVersioning​

    Since JATOS version >= 3.5.6 - 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

    jatos.groupSessionVersioning = false; // Turns off versioning
    - +JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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. 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.

    Examples

    1. Get a field from the Group Session

      Given the Group Session is {"a": 1000, "b": "watermelon"}

      // 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.

    2. 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"}}

      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.

    Examples

    1. Set a field in the Group Session

      If the Group Session is {"a": 1234}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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.

    Example

    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'.

    Examples

    1. Set the whole Group Session at once

      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.

    2. Use returned Promise to handle success or failure

      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 {}.

    Examples

    1. Clear the whole Group Session

      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.

    2. Use returned Promise to handle success or failure

      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. 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.

    Example

    Given the Group Session is {"a": {"a1": "foo", "a2": "bar"}, "b": 999}

    jatos.groupSession.find("/a/a1"); // returns "foo"
    jatos.groupSession.find("/b"); // returns 999

    the first line returns "foo" and the second 999.

    jatos.groupSession.defined​

    Since JATOS version >= 3.1.8 - 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).

    Example

    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).

    Example

    Given the Group Session is {"a": 123, "b": {"b1": "flowers", "b2": "animals"}}

    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.

    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). If the path already exists in the Group Session the value will be overwritten.

    Examples

    1. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Example with an array: Put the object {id: 123, name: "Max"} after the second position of the array with the path /subjects:

      jatos.groupSession.add("/subjects/2", {id: 123, name: "Max"})
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Example of how to append to the end of an array: use /- after the arrays name:

      jatos.groupSession.add("/subjects/-", {id: 124, name: "Adam"})
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    5. Have a series of Group Session changes

      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).

    Examples

    1. Remove a field from the Group Session

      If the Group Session is {"a": 100, "b": 123} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Replace a field in the Group Session

      If the Group Session is {"a": 100, "b": 123} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Copy a field in the Group Session from one location to another

      If the Group Session is {"a": "jatos"} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Move a field in the Group Session from one location to another

      If the Group Session is {"a": "jatos"} and one calls

      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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.move("/a", "/b")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    jatos.groupSessionVersioning​

    Since JATOS version >= 3.5.6 - 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

    jatos.groupSessionVersioning = false; // Turns off versioning
    + \ No newline at end of file diff --git a/3.6.x/jsPsych-and-JATOS.html b/3.6.x/jsPsych-and-JATOS.html index b0a223055..18a400bf2 100644 --- a/3.6.x/jsPsych-and-JATOS.html +++ b/3.6.x/jsPsych-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    jsPsych and JATOS

    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.

    In our 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 (Jatosify).

    How to turn your jsPsych experiment into a JATOS study​

    1. Include the jatos.js library in the <head>

      <script src="/assets/javascripts/jatos.js"></script>

      Remember: Any URL or file path in a HTML file should only use '/' as a file path separator - even on Windows systems.

    2. Wrap jsPsych's init call jsPsych.init in a jatos.onLoad call

      jatos.onLoad(function() {
        jsPsych.init( {
          // ...
        });
      });

    That's all. If you additionally want to send your result data to JATOS read on.

    Send jsPsych's result data back to JATOS​

    Here we use jsPsych's function jsPsych.data.getData() (jsPsych 5) or jsPsych.data.get().json() (jsPsych 6) to collect the data into a JSON-formatted string. Then we use JATOS' function jatos.submitResultData to send your result to JATOS and ask JATOS to move to the next component, if there is one.

    jsPsych 5​

    jatos.onLoad(function() {
      jsPsych.init( {
        // ...
        on_finish: function() {
          var resultJson = JSON.stringify(jsPsych.data.getData());
          jatos.submitResultData(resultJson, jatos.startNextComponent);
        }
      }
    });

    jsPsych 6​

    jatos.onLoad(function() {
      jsPsych.init( {
        // ...
        on_finish: function() {
          var resultJson = jsPsych.data.get().json();
          jatos.submitResultData(resultJson, jatos.startNextComponent);
        }
      });
    });

    Adding additional HTML snippets to a jPsych code (e.g. cancel button)​

    jsPsych has the habit of cleaning the HTML's body and fill it with its own code. This means that whatever you write between the <body> tags will be ignored. But you might want to add some additional HTML element like a cancel button to the page without changing the jsPsych plugin or writing a new one. How can this be done?

    Luckily jsPsych offers a callback function on_load. Whatever we write in there is called after jsPsych did its body clean-up. So you could add your extra HTML elements in there.

    Hint: Since JATOS version 3.5.1 it's much easier to add a cancel button: use jatos.addAbortButton.

    Here's an example (you need jQuery for this one to work):

    var my_trial = {
      type: 'some-plugin',
      on_load: function() {
        $("body").append('<button onclick="jatos.abortStudy()">Cancel Study</button>');
      },
      ...

    And without jQuery it's more cumbersome:

    var my_trial = {
      type: 'some-plugin',
      on_load: function() {
        var button = document.createElement("button");
        button.innerHTML = "Cancel Study";
        document.body.appendChild(button);
        button.addEventListener("click", function() {
          jatos.abortStudy();
        });
      },
      ...

    You probably want to add some styling but this is how it works in principle.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    jsPsych and JATOS

    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.

    In our 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 (Jatosify).

    How to turn your jsPsych experiment into a JATOS study​

    1. Include the jatos.js library in the <head>

      <script src="/assets/javascripts/jatos.js"></script>

      Remember: Any URL or file path in a HTML file should only use '/' as a file path separator - even on Windows systems.

    2. Wrap jsPsych's init call jsPsych.init in a jatos.onLoad call

      jatos.onLoad(function() {
        jsPsych.init( {
          // ...
        });
      });

    That's all. If you additionally want to send your result data to JATOS read on.

    Send jsPsych's result data back to JATOS​

    Here we use jsPsych's function jsPsych.data.getData() (jsPsych 5) or jsPsych.data.get().json() (jsPsych 6) to collect the data into a JSON-formatted string. Then we use JATOS' function jatos.submitResultData to send your result to JATOS and ask JATOS to move to the next component, if there is one.

    jsPsych 5​

    jatos.onLoad(function() {
      jsPsych.init( {
        // ...
        on_finish: function() {
          var resultJson = JSON.stringify(jsPsych.data.getData());
          jatos.submitResultData(resultJson, jatos.startNextComponent);
        }
      }
    });

    jsPsych 6​

    jatos.onLoad(function() {
      jsPsych.init( {
        // ...
        on_finish: function() {
          var resultJson = jsPsych.data.get().json();
          jatos.submitResultData(resultJson, jatos.startNextComponent);
        }
      });
    });

    Adding additional HTML snippets to a jPsych code (e.g. cancel button)​

    jsPsych has the habit of cleaning the HTML's body and fill it with its own code. This means that whatever you write between the <body> tags will be ignored. But you might want to add some additional HTML element like a cancel button to the page without changing the jsPsych plugin or writing a new one. How can this be done?

    Luckily jsPsych offers a callback function on_load. Whatever we write in there is called after jsPsych did its body clean-up. So you could add your extra HTML elements in there.

    Hint: Since JATOS version 3.5.1 it's much easier to add a cancel button: use jatos.addAbortButton.

    Here's an example (you need jQuery for this one to work):

    var my_trial = {
      type: 'some-plugin',
      on_load: function() {
        $("body").append('<button onclick="jatos.abortStudy()">Cancel Study</button>');
      },
      ...

    And without jQuery it's more cumbersome:

    var my_trial = {
      type: 'some-plugin',
      on_load: function() {
        var button = document.createElement("button");
        button.innerHTML = "Cancel Study";
        document.body.appendChild(button);
        button.addEventListener("click", function() {
          jatos.abortStudy();
        });
      },
      ...

    You probably want to add some styling but this is how it works in principle.

    + \ No newline at end of file diff --git a/3.6.x/labjs-and-JATOS.html b/3.6.x/labjs-and-JATOS.html index 8ab2c0a79..79a965208 100644 --- a/3.6.x/labjs-and-JATOS.html +++ b/3.6.x/labjs-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.6.x and earlier

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their Builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    - +
    Skip to main content
    Version: 3.6.x and earlier

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their Builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    + \ No newline at end of file diff --git a/3.6.x/tags.html b/3.6.x/tags.html index c3fe721d1..212a45c61 100644 --- a/3.6.x/tags.html +++ b/3.6.x/tags.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    Tags

    - + \ No newline at end of file diff --git a/3.6.x/tags/jatos-js.html b/3.6.x/tags/jatos-js.html index a524596cf..1bab94d35 100644 --- a/3.6.x/tags/jatos-js.html +++ b/3.6.x/tags/jatos-js.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    One doc tagged with "jatos.js"

    View All Tags

    jatos.js Reference

    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 the variables and functions of the jatos.js library.

    - + \ No newline at end of file diff --git a/3.6.x/tags/javascript.html b/3.6.x/tags/javascript.html index 679f2084c..3416b357f 100644 --- a/3.6.x/tags/javascript.html +++ b/3.6.x/tags/javascript.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    One doc tagged with "javascript"

    View All Tags

    jatos.js Reference

    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 the variables and functions of the jatos.js library.

    - + \ No newline at end of file diff --git a/3.6.x/tags/js.html b/3.6.x/tags/js.html index 9d92f2ce7..842bafa21 100644 --- a/3.6.x/tags/js.html +++ b/3.6.x/tags/js.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    One doc tagged with "js"

    View All Tags

    jatos.js Reference

    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 the variables and functions of the jatos.js library.

    - + \ No newline at end of file diff --git a/3.6.x/tags/library.html b/3.6.x/tags/library.html index 96f9c9b00..7dd17031e 100644 --- a/3.6.x/tags/library.html +++ b/3.6.x/tags/library.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    One doc tagged with "library"

    View All Tags

    jatos.js Reference

    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 the variables and functions of the jatos.js library.

    - + \ No newline at end of file diff --git a/3.6.x/tags/reference.html b/3.6.x/tags/reference.html index 61163f3e3..ad1e89fb0 100644 --- a/3.6.x/tags/reference.html +++ b/3.6.x/tags/reference.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    One doc tagged with "reference"

    View All Tags

    jatos.js Reference

    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 the variables and functions of the jatos.js library.

    - + \ No newline at end of file diff --git a/3.7.x/Adapt-pre-written-code-to-run-it-in-JATOS.html b/3.7.x/Adapt-pre-written-code-to-run-it-in-JATOS.html index 2a0a36c4b..8798a759d 100644 --- a/3.7.x/Adapt-pre-written-code-to-run-it-in-JATOS.html +++ b/3.7.x/Adapt-pre-written-code-to-run-it-in-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Adapt pre written code to run it in JATOS

    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.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Create the study in your local JATOS​

    1. Create a new study with the 'New Study' button in JATOS' header. Choose a study title and a folder name. Leave the other fields empty for now and click 'Create'. JATOS will have created a new folder within your assets root folder (default is /path_to_your_JATOS/study_assets_root/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. Back in the JATOS GUI, and within the newly created study, create a new component by clicking 'Components' and then 'New'. Choose a component title and set the HTML file name, to the name of the HTML file you just copied into the study folder.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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's and component's 'JSON input data'. 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.
    - +
    Skip to main content
    Version: 3.7.x

    Adapt pre written code to run it in JATOS

    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.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Create the study in your local JATOS​

    1. Create a new study with the 'New Study' button in JATOS' header. Choose a study title and a folder name. Leave the other fields empty for now and click 'Create'. JATOS will have created a new folder within your assets root folder (default is /path_to_your_JATOS/study_assets_root/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. Back in the JATOS GUI, and within the newly created study, create a new component by clicking 'Components' and then 'New'. Choose a component title and set the HTML file name, to the name of the HTML file you just copied into the study folder.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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's and component's 'JSON input data'. 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.
    + \ No newline at end of file diff --git a/3.7.x/Administration.html b/3.7.x/Administration.html index b35f8bc61..cfeae3444 100644 --- a/3.7.x/Administration.html +++ b/3.7.x/Administration.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    On the menu you will find links to two additional administration pages:

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    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.

    For larger JATOS installation it can take up to a couple minutes to gather all data for this page

    Studies Administration

    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.
    - +
    Skip to main content
    Version: 3.7.x

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    On the menu you will find links to two additional administration pages:

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    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.

    For larger JATOS installation it can take up to a couple minutes to gather all data for this page

    Studies Administration

    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.
    + \ No newline at end of file diff --git a/3.7.x/Bring-your-JATOS-online.html b/3.7.x/Bring-your-JATOS-online.html index 2cf16cc6f..20c89382e 100644 --- a/3.7.x/Bring-your-JATOS-online.html +++ b/3.7.x/Bring-your-JATOS-online.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.7.x

    Bring your JATOS online

    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 timeSetup difficultyCostNumber of JATOS user / JATOS workers
    1. Expose your local JATOSfasteasynoneyou / few †
    2. Cloud serverfast to mediumdepends on your vendoryesmany / many ‡
    3. Own servermedium to slow (depends on your IT)needs admin skillsask your ITmany / many ‡

    †) 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

    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 or JATOS on AWS (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

    - +‡) 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

    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 or JATOS on AWS (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

    + \ No newline at end of file diff --git a/3.7.x/Change-studys-members.html b/3.7.x/Change-studys-members.html index b69269190..d771a7d15 100644 --- a/3.7.x/Change-studys-members.html +++ b/3.7.x/Change-studys-members.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Change study's members

    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&#39;s members button

    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&#39;s members

    - +
    Skip to main content
    Version: 3.7.x

    Change study's members

    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&#39;s members button

    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&#39;s members

    + \ No newline at end of file diff --git a/3.7.x/Configure-JATOS-on-a-Server.html b/3.7.x/Configure-JATOS-on-a-Server.html index b5ee792d6..b24fedcc1 100644 --- a/3.7.x/Configure-JATOS-on-a-Server.html +++ b/3.7.x/Configure-JATOS-on-a-Server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Configure JATOS on a Server

    Remember to always restart JATOS after making any changes to the configuration (./loader.sh restart)

    IP / domain and port​

    By default JATOS binds to all locally available IP addresses including 127.0.0.1 on port 9000. If you don't want to use a proxy in front of JATOS, you have several ways to configure the host name or IP address and the port:

    1. It is possible to set up IP and port via conf/production.conf: Edit play.server.http.address and play.server.http.port and restart JATOS. E.g. to run on IP 192.168.0.100 and port 80:

      play.server.http.address = "192.168.0.100"
      play.server.http.port = 80

    2. Via command-line arguments -Dhttp.address and -Dhttp.port, e.g. with the following command you'd start JATOS with IP 10.0.0.1 and port 80

      ./loader.sh start -Dhttp.address=10.0.0.1 -Dhttp.port=80

    3. (DEPRECATED) In loader.sh change the values of 'address' and 'port' according to your IP address or domain name and port. Restart JATOS after editing.

      address="172.16.0.1"
      port="8080"

    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 JATOS' URL all start with "www.example.org/mybasepath/". This can be achieved in two ways:

    1. Via the command-line argument -DJATOS_URL_BASE_PATH, e.g.

      ./loader.sh start -DJATOS_URL_BASE_PATH="/mybasepath/"

    2. Via conf/production.conf: change play.http.context

      play.http.context = "/mybasepath/"

    3. Via the environment variable JATOS_URL_BASE_PATH, e.g.

      export JATOS_URL_BASE_PATH="/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 (which is recommended anyway).

    Study assets root path​

    By default the study assets root folder (where all your study's HTML, JavaScript files etc. are stored) is located within JATOS installation's folder in study_assets_root. There are three ways to change this path:

    1. Via the command-line argument -DJATOS_STUDY_ASSETS_ROOT_PATH, e.g.

      ./loader.sh start -DJATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

    2. Via conf/production.conf: change jatos.studyAssetsRootPath

      jatos.studyAssetsRootPath="/path/to/my/jatos_study_assets_root"

    3. Via the environment variable JATOS_STUDY_ASSETS_ROOT_PATH, e.g. the following export adds it to the env variables:

      export JATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

    MySQL Database​

    See JATOS with MySQL

    JVM arguments​

    All JVM arguments can be used with loader.sh but all arguments starting with -X need an extra suffix -J. The most important one is -Xmx, the one to limit JATOS memory usage (to change JVM's max heap memory to be precise). It has to be written as -J-Xmx:

    ./loader.sh start -J-Xmx4G   # Allow max 4 GB (heap) memory

    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 in the conf/production.conf with the following two properties.

    • jatos.user.password.length - Set with an positive integer (default is 7)
    • jatos.user.password.strength - Set to 0, 1, 2, or 3 (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 (#?!@$%^&*-)
      • 3: At least one uppercase Latin letter, one lowercase Latin letter, one number and one special character (#?!@$%^&*-)

    Study result data​

    You can change the allowed size of a component's result data. This can be used to reduce the load on the server, especially network and database. Sometimes its necessary to increase the value if certain studies have larger result data needs. The property for this in conf/production.conf is jatos.resultData.maxSize. By default it's set to 5 MB per component run.

    E.g. to reduce the allowed size per component to 1 MB:

    jatos.resultData.maxSize = 1MB

    Uploading of study result files​

    There are three ways to configure the uploads:

    1. Via conf/production.conf

      • jatos.resultUploads.enabled - Enables study result files uploads (default is true)
      • jatos.resultUploads.path - Path in the file system where the uploaded result files will be stored (default is './result_uploads')
      • jatos.resultUploads.maxFileSize - Max file size for one single uploaded result file (default is 30 MB)
      • jatos.resultUploads.limitPerStudyRun - Limit of all uploaded result files of one single study run (default is 50MB)

    2. Via environment variables (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE)

      E.g.

      export JATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder"
      export JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB
      export JATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

    3. Via command-line arguments (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE)

      E.g.

      ./loader.sh start -DJATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder" -DJATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB -DJATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

    Study logs​

    There are three ways to change the configuration of the study logs:

    1. Via conf/production.conf

      • jatos.studyLogs.enabled - Enables Study Logs (default is true)
      • jatos.studyLogs.path - Path in the file system where the Study Logs will be stored (default is './study_logs')

    2. The path can be configured via environment variables

      E.g.

      export JATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

    3. The path can be configured via command-line arguments

      E.g.

      ./loader.sh start -DJATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

    LDAP authentication​

    By default JATOS uses only locally stored users and no LDAP. LDAP configuration is only possible in conf/production.conf. At the moment LDAP users still have to be created manually in JATOS' User manager (with the checkbox LDAP turned on).- only authentication is done via LDAP.

    • jatos.user.authentication.ldap.url - Specifies URL of the LDAP server. Not set or an empty string means no authentication via LDAP.
    • jatos.user.authentication.ldap.basedn - LDAP base DN(s) (distinguished name). 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 means no authentication via LDAP.
    • jatos.user.authentication.ldap.admin.dn - DN (distinguished name) 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 needed.
    • jatos.user.authentication.ldap.admin.password - Password of the admin user
    • jatos.user.authentication.ldap.timeout - Time in milliseconds JATOS waits for a response from your LDAP server. Default is 5000 ms.

    If your LDAP uses encryption, you have to add your certificate to JATOS' trusted certificates defined with play.ws.ssl.trustManager.stores. 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.

    User session configuration​

    The user session is part of JATOS secuity measurments (more about security) and can be configured in conf/production.conf.

    • jatos.userSession.validation - toggles user session validation. If turned on (true) only the IP which was used at login time is allowed to be used for subsequent requests by this user. This helps preventing session hijacking and adds an addional layer of security. But on the downside it also prevents using the same user in JATOS from different browsers at the same time. By default it is set to false to allow an easy use of a local JATOS. On a server installation it should be set to true, although sometimes this not possible, e.g. if your users have an often changing, dynamic IP address. WARNING: Turning off the user session validation reduces JATOS security!

    Other configs are:

    • jatos.userSession.timeout - time in minutes a user stays logged in (default is 1440 = 1 day)
    • jatos.userSession.inactivity - defines the time in minutes a user is automatically logged out after inactivity (default is 60)

    Customize JATOS' home page​

    More here.

    Other configuration in production.conf​

    Some other properties can be configured in the conf/production.conf.

    • play.http.session.secure - secure session cookie: set true to restrict user access to HTTPS (default is false)
    • jatos.idCookies.secure - secure ID cookies: set true to restrict worker access to HTTPS (default is false)
    • jatos.idCookies.sameSite - defines the ID cookies' 'SameSite' attribute: allowed values are None, Lax, or Strict. Default is None.
    • jatos.studyMembers.allowAddAllUsers - Allow to add all users that exist on a JATOS to be added at once as members of a study. Default is false.
    • jatos.resultData.export.useTmpFile - If true, result data that are fetched from the database are first stored in a temporary file and only when they are all gathered the file is sent to the browser. If false the result data are streamed directly from the database to the browser. Default is false.
    • jatos.maxResultsDbQuerySize - Maximal number of results to be fetched from the DB at once (default is 10)
    • jatos.user.authentication.oauth.googleClientId - Activate Google Sign-In by putting your Google Client ID here (looks similar to this one "1234567890-abc123abc123.apps.googleusercontent.com")
    • jatos.user.role.allowSuperuser - Activate Superuser role by putting 'true' (default is 'false')
    • jatos.studyAdmin.showStudyAssetsSize - If set to 'false' it the 'Study Assets Size' column will be shown in the Study Admin page. Since calculating the study assets size can take some time on larger JATOS installations with slow disks, it can make sense to turn it off. Default is 'true'.
    • jatos.studyAdmin.showResultDataSize - If set to 'false' it the 'Result Data Size' column will be shown in the Study Admin page. Since calculating the result data can take some time on larger JATOS installations with a slow database, it can make sense to turn it off. Default is 'true'.
    • jatos.studyAdmin.showResultFileSize - If set to 'false' it the 'Result File Size' column will be shown in the Study Admin page. Since calculating the result file size can take some time on larger JATOS installations with slow disks, it can make sense to turn it off. Default is 'true'.

    Apart from those all configuration properties possible in the Play Framework are possible in JATOS' production.conf too, e.g.

    • play.pidfile.path - Path to the file that contains the process id of the started JATOS application (default is ./RUNNING_PID)
    - +
    Skip to main content
    Version: 3.7.x

    Configure JATOS on a Server

    Remember to always restart JATOS after making any changes to the configuration (./loader.sh restart)

    IP / domain and port​

    By default JATOS binds to all locally available IP addresses including 127.0.0.1 on port 9000. If you don't want to use a proxy in front of JATOS, you have several ways to configure the host name or IP address and the port:

    1. It is possible to set up IP and port via conf/production.conf: Edit play.server.http.address and play.server.http.port and restart JATOS. E.g. to run on IP 192.168.0.100 and port 80:

      play.server.http.address = "192.168.0.100"
      play.server.http.port = 80

    2. Via command-line arguments -Dhttp.address and -Dhttp.port, e.g. with the following command you'd start JATOS with IP 10.0.0.1 and port 80

      ./loader.sh start -Dhttp.address=10.0.0.1 -Dhttp.port=80

    3. (DEPRECATED) In loader.sh change the values of 'address' and 'port' according to your IP address or domain name and port. Restart JATOS after editing.

      address="172.16.0.1"
      port="8080"

    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 JATOS' URL all start with "www.example.org/mybasepath/". This can be achieved in two ways:

    1. Via the command-line argument -DJATOS_URL_BASE_PATH, e.g.

      ./loader.sh start -DJATOS_URL_BASE_PATH="/mybasepath/"

    2. Via conf/production.conf: change play.http.context

      play.http.context = "/mybasepath/"

    3. Via the environment variable JATOS_URL_BASE_PATH, e.g.

      export JATOS_URL_BASE_PATH="/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 (which is recommended anyway).

    Study assets root path​

    By default the study assets root folder (where all your study's HTML, JavaScript files etc. are stored) is located within JATOS installation's folder in study_assets_root. There are three ways to change this path:

    1. Via the command-line argument -DJATOS_STUDY_ASSETS_ROOT_PATH, e.g.

      ./loader.sh start -DJATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

    2. Via conf/production.conf: change jatos.studyAssetsRootPath

      jatos.studyAssetsRootPath="/path/to/my/jatos_study_assets_root"

    3. Via the environment variable JATOS_STUDY_ASSETS_ROOT_PATH, e.g. the following export adds it to the env variables:

      export JATOS_STUDY_ASSETS_ROOT_PATH="/path/to/my/assets/root/folder"

    MySQL Database​

    See JATOS with MySQL

    JVM arguments​

    All JVM arguments can be used with loader.sh but all arguments starting with -X need an extra suffix -J. The most important one is -Xmx, the one to limit JATOS memory usage (to change JVM's max heap memory to be precise). It has to be written as -J-Xmx:

    ./loader.sh start -J-Xmx4G   # Allow max 4 GB (heap) memory

    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 in the conf/production.conf with the following two properties.

    • jatos.user.password.length - Set with an positive integer (default is 7)
    • jatos.user.password.strength - Set to 0, 1, 2, or 3 (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 (#?!@$%^&*-)
      • 3: At least one uppercase Latin letter, one lowercase Latin letter, one number and one special character (#?!@$%^&*-)

    Study result data​

    You can change the allowed size of a component's result data. This can be used to reduce the load on the server, especially network and database. Sometimes its necessary to increase the value if certain studies have larger result data needs. The property for this in conf/production.conf is jatos.resultData.maxSize. By default it's set to 5 MB per component run.

    E.g. to reduce the allowed size per component to 1 MB:

    jatos.resultData.maxSize = 1MB

    Uploading of study result files​

    There are three ways to configure the uploads:

    1. Via conf/production.conf

      • jatos.resultUploads.enabled - Enables study result files uploads (default is true)
      • jatos.resultUploads.path - Path in the file system where the uploaded result files will be stored (default is './result_uploads')
      • jatos.resultUploads.maxFileSize - Max file size for one single uploaded result file (default is 30 MB)
      • jatos.resultUploads.limitPerStudyRun - Limit of all uploaded result files of one single study run (default is 50MB)

    2. Via environment variables (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE)

      E.g.

      export JATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder"
      export JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB
      export JATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

    3. Via command-line arguments (JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN and JATOS_RESULT_UPLOADS_MAX_FILE_SIZE)

      E.g.

      ./loader.sh start -DJATOS_RESULT_UPLOADS_PATH="/path/to/my/result/upload/folder" -DJATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN=100MB -DJATOS_RESULT_UPLOADS_MAX_FILE_SIZE=50MB

    Study logs​

    There are three ways to change the configuration of the study logs:

    1. Via conf/production.conf

      • jatos.studyLogs.enabled - Enables Study Logs (default is true)
      • jatos.studyLogs.path - Path in the file system where the Study Logs will be stored (default is './study_logs')

    2. The path can be configured via environment variables

      E.g.

      export JATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

    3. The path can be configured via command-line arguments

      E.g.

      ./loader.sh start -DJATOS_STUDY_LOGS_PATH="/path/to/my/study/logs/folder"

    LDAP authentication​

    By default JATOS uses only locally stored users and no LDAP. LDAP configuration is only possible in conf/production.conf. At the moment LDAP users still have to be created manually in JATOS' User manager (with the checkbox LDAP turned on).- only authentication is done via LDAP.

    • jatos.user.authentication.ldap.url - Specifies URL of the LDAP server. Not set or an empty string means no authentication via LDAP.
    • jatos.user.authentication.ldap.basedn - LDAP base DN(s) (distinguished name). 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 means no authentication via LDAP.
    • jatos.user.authentication.ldap.admin.dn - DN (distinguished name) 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 needed.
    • jatos.user.authentication.ldap.admin.password - Password of the admin user
    • jatos.user.authentication.ldap.timeout - Time in milliseconds JATOS waits for a response from your LDAP server. Default is 5000 ms.

    If your LDAP uses encryption, you have to add your certificate to JATOS' trusted certificates defined with play.ws.ssl.trustManager.stores. 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.

    User session configuration​

    The user session is part of JATOS secuity measurments (more about security) and can be configured in conf/production.conf.

    • jatos.userSession.validation - toggles user session validation. If turned on (true) only the IP which was used at login time is allowed to be used for subsequent requests by this user. This helps preventing session hijacking and adds an addional layer of security. But on the downside it also prevents using the same user in JATOS from different browsers at the same time. By default it is set to false to allow an easy use of a local JATOS. On a server installation it should be set to true, although sometimes this not possible, e.g. if your users have an often changing, dynamic IP address. WARNING: Turning off the user session validation reduces JATOS security!

    Other configs are:

    • jatos.userSession.timeout - time in minutes a user stays logged in (default is 1440 = 1 day)
    • jatos.userSession.inactivity - defines the time in minutes a user is automatically logged out after inactivity (default is 60)

    Customize JATOS' home page​

    More here.

    Other configuration in production.conf​

    Some other properties can be configured in the conf/production.conf.

    • play.http.session.secure - secure session cookie: set true to restrict user access to HTTPS (default is false)
    • jatos.idCookies.secure - secure ID cookies: set true to restrict worker access to HTTPS (default is false)
    • jatos.idCookies.sameSite - defines the ID cookies' 'SameSite' attribute: allowed values are None, Lax, or Strict. Default is None.
    • jatos.studyMembers.allowAddAllUsers - Allow to add all users that exist on a JATOS to be added at once as members of a study. Default is false.
    • jatos.resultData.export.useTmpFile - If true, result data that are fetched from the database are first stored in a temporary file and only when they are all gathered the file is sent to the browser. If false the result data are streamed directly from the database to the browser. Default is false.
    • jatos.maxResultsDbQuerySize - Maximal number of results to be fetched from the DB at once (default is 10)
    • jatos.user.authentication.oauth.googleClientId - Activate Google Sign-In by putting your Google Client ID here (looks similar to this one "1234567890-abc123abc123.apps.googleusercontent.com")
    • jatos.user.role.allowSuperuser - Activate Superuser role by putting 'true' (default is 'false')
    • jatos.studyAdmin.showStudyAssetsSize - If set to 'false' it the 'Study Assets Size' column will be shown in the Study Admin page. Since calculating the study assets size can take some time on larger JATOS installations with slow disks, it can make sense to turn it off. Default is 'true'.
    • jatos.studyAdmin.showResultDataSize - If set to 'false' it the 'Result Data Size' column will be shown in the Study Admin page. Since calculating the result data can take some time on larger JATOS installations with a slow database, it can make sense to turn it off. Default is 'true'.
    • jatos.studyAdmin.showResultFileSize - If set to 'false' it the 'Result File Size' column will be shown in the Study Admin page. Since calculating the result file size can take some time on larger JATOS installations with slow disks, it can make sense to turn it off. Default is 'true'.

    Apart from those all configuration properties possible in the Play Framework are possible in JATOS' production.conf too, e.g.

    • play.pidfile.path - Path to the file that contains the process id of the started JATOS application (default is ./RUNNING_PID)
    + \ No newline at end of file diff --git a/3.7.x/Connect-to-Mechanical-Turk.html b/3.7.x/Connect-to-Mechanical-Turk.html index 3285b9f1c..21d714014 100644 --- a/3.7.x/Connect-to-Mechanical-Turk.html +++ b/3.7.x/Connect-to-Mechanical-Turk.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    - +
    Skip to main content
    Version: 3.7.x

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    + \ No newline at end of file diff --git a/3.7.x/Contact-us.html b/3.7.x/Contact-us.html index d032d12e9..9b9355b56 100644 --- a/3.7.x/Contact-us.html +++ b/3.7.x/Contact-us.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    - +
    Skip to main content
    Version: 3.7.x

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    + \ No newline at end of file diff --git a/3.7.x/Create-a-new-study.html b/3.7.x/Create-a-new-study.html index 7bca061a4..cbecb37b6 100644 --- a/3.7.x/Create-a-new-study.html +++ b/3.7.x/Create-a-new-study.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Create a new study

    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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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.

    Press the New Study button in the header of your local JATOS. Then edit the study properties and add new components manually. All source code for your study has to got into the study assets folder you defined in the the study properties. 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) as a prototype and modify it bit by bit. Press on the Import button in the header and select the file of the study. Then see the source code in your study assets folder, which is usually in your JATOS installation folder.

    - +
    Skip to main content
    Version: 3.7.x

    Create a new study

    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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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.

    Press the New Study button in the header of your local JATOS. Then edit the study properties and add new components manually. All source code for your study has to got into the study assets folder you defined in the the study properties. 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) as a prototype and modify it bit by bit. Press on the Import button in the header and select the file of the study. Then see the source code in your study assets folder, which is usually in your JATOS installation folder.

    + \ No newline at end of file diff --git a/3.7.x/Cross-sectional-and-longitudinal-studies.html b/3.7.x/Cross-sectional-and-longitudinal-studies.html index 980b27152..57145409f 100644 --- a/3.7.x/Cross-sectional-and-longitudinal-studies.html +++ b/3.7.x/Cross-sectional-and-longitudinal-studies.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    - +
    Skip to main content
    Version: 3.7.x

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    + \ No newline at end of file diff --git a/3.7.x/Customize-JATOS-Home-Page.html b/3.7.x/Customize-JATOS-Home-Page.html index feffd258e..2f5ab2c50 100644 --- a/3.7.x/Customize-JATOS-Home-Page.html +++ b/3.7.x/Customize-JATOS-Home-Page.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Customize JATOS' Home Page

    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/production.conf 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.

    template customized home page

    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.

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. Configure JATOS: In your JATOS installation folder edit conf/production.conf - 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    - +
    Skip to main content
    Version: 3.7.x

    Customize JATOS' Home Page

    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/production.conf 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.

    template customized home page

    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.

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. Configure JATOS: In your JATOS installation folder edit conf/production.conf - 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    + \ No newline at end of file diff --git a/3.7.x/Data-Privacy-and-Ethics.html b/3.7.x/Data-Privacy-and-Ethics.html index a34911988..75b295442 100644 --- a/3.7.x/Data-Privacy-and-Ethics.html +++ b/3.7.x/Data-Privacy-and-Ethics.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Data Privacy and Ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    - +
    Skip to main content
    Version: 3.7.x

    Data Privacy and Ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    + \ No newline at end of file diff --git a/3.7.x/Deploy-to-a-server-installation.html b/3.7.x/Deploy-to-a-server-installation.html index aca962ab0..00cf75cb1 100644 --- a/3.7.x/Deploy-to-a-server-installation.html +++ b/3.7.x/Deploy-to-a-server-installation.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.7.x

    Deploy to a server installation

    Usually you conveniently develop your study on your local computer where you have a local installation of JATOS. Then just use the export and import buttons in your installations to transfer the study to your JATOS server.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Here's a little sketch of the same three steps above jzip workflow

    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 black bar on top. A server installation has a light-grey bar.
    • A .jzip file is a normal .zip file. We just changed the name to make this process clearer. (JATOS users got confused and often tried to unzip the file they had downloaded, add HTML files in it, and re-zip it. This will lead to all sorts of problems. Don't do this. -You should do all modifications of files and study properties from the JATOS GUI.)
    • 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 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.
    - +You should do all modifications of files and study properties from the JATOS GUI.)
  • 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 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.
    • + \ No newline at end of file diff --git a/3.7.x/End-page-after-your-study-finished.html b/3.7.x/End-page-after-your-study-finished.html index 7ca938c64..7d266b9d9 100644 --- a/3.7.x/End-page-after-your-study-finished.html +++ b/3.7.x/End-page-after-your-study-finished.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    End page - After your study finished

    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 finshed. 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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    - +
    Skip to main content
    Version: 3.7.x

    End page - After your study finished

    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 finshed. 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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    + \ No newline at end of file diff --git a/3.7.x/Example-Group-Studies.html b/3.7.x/Example-Group-Studies.html index 7f00cf456..f356a6611 100644 --- a/3.7.x/Example-Group-Studies.html +++ b/3.7.x/Example-Group-Studies.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    - +
    Skip to main content
    Version: 3.7.x

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    + \ No newline at end of file diff --git a/3.7.x/Expose-your-local-JATOS.html b/3.7.x/Expose-your-local-JATOS.html index 7e69ff562..d0b1f1990 100644 --- a/3.7.x/Expose-your-local-JATOS.html +++ b/3.7.x/Expose-your-local-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create study links 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.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create study links 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/.

    - +
    Skip to main content
    Version: 3.7.x

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create study links 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.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create study links 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/.

    + \ No newline at end of file diff --git a/3.7.x/Get-started.html b/3.7.x/Get-started.html index 34e1c950e..fa28d5bb9 100644 --- a/3.7.x/Get-started.html +++ b/3.7.x/Get-started.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.7.x

    Get started

    Get started in 4 steps​

    1. Download JATOS and install a local instance

    2. Open JATOS' GUI by going to localhost:9000 in your browser window

    3. Download and import an example study

      1. Download one of the Example Studies, e.g. the 'Go- / No-Go Task' with jsPsych. Do not unzip the downloaded file.

      2. Import the study into JATOS: Go to JATOS' GUI in your browser and click on Import Study in the header. Choose the .jzip (or .zip) file you just downloaded. The imported study should appear in the sidebar on the left.

    4. 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).

      Here's a screenshot of a study's results view: Results View screenshot

    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/.

    Here's a screenshot of a component's properties view: -GUI screenshot

    - +GUI screenshot

    + \ No newline at end of file diff --git a/3.7.x/Install-JATOS-via-Docker.html b/3.7.x/Install-JATOS-via-Docker.html index afb9354b8..89a270fdf 100644 --- a/3.7.x/Install-JATOS-via-Docker.html +++ b/3.7.x/Install-JATOS-via-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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).

    Since 3.7.4 Docker images for JATOS exist for arm64 and amd64 CPU architectures.

    Install JATOS locally with a Docker container​

    1. Install Docker locally on your computer (not covered here)

    2. Go to your shell or command line interface

    3. Pull JATOS image

      • either latest:
      docker pull jatos/jatos:latest
      • or a specific one (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    4. Run JATOS (use your image version)

      docker run -d -p 9000:9000 jatos/jatos:latest

      The -d argument specifies to run this container in detached mode (in the backgroud) and the -p is responsible for the port mapping.

    5. You can check that the new container is running: In your browser go to localhost:9000 - it should show the JATOS login screen. Or use docker ps - in the line with jatos/jatos the status should say up.

    Troubleshooting: By removing the -d argument (e.g. docker run -p 9000:9000 jatos/jatos:latest) you get JATOS' logs printed in your shell - although you don't run it in detached mode in the background anymore.

    Troubleshooting 2nd: Although usually not necessary maybe you want to have a look into the running container and start a Bash terminal:

    docker exec -it running-jatos-container-id /bin/bash

    Change port​

    With Docker you can easily change JATOS' port (actually we change the port mapping of JATOS' docker container). Just use Docker -p argument and specify your port. E.g. to run JATOS on standard HTTP port 80 use:

    docker run -d -p 80:9000 jatos/jatos:latest

    Configure with environment variables​

    All environment variables that can be used to configure a normal JATOS server installation 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 a host with the IP 172.17.0.2 and with the default port 3306 use the following command (change username and password of your MySQL account):

    docker run -e JATOS_DB_URL='jdbc:mysql://172.17.0.2/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' -e JATOS_DB_USERNAME='root' -e JATOS_DB_PASSWORD='password' -e JATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver -e JATOS_JPA=mysqlPersistenceUnit -p 9000:9000 jatos/jatos:latest
    - +
    Skip to main content
    Version: 3.7.x

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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).

    Since 3.7.4 Docker images for JATOS exist for arm64 and amd64 CPU architectures.

    Install JATOS locally with a Docker container​

    1. Install Docker locally on your computer (not covered here)

    2. Go to your shell or command line interface

    3. Pull JATOS image

      • either latest:
      docker pull jatos/jatos:latest
      • or a specific one (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    4. Run JATOS (use your image version)

      docker run -d -p 9000:9000 jatos/jatos:latest

      The -d argument specifies to run this container in detached mode (in the backgroud) and the -p is responsible for the port mapping.

    5. You can check that the new container is running: In your browser go to localhost:9000 - it should show the JATOS login screen. Or use docker ps - in the line with jatos/jatos the status should say up.

    Troubleshooting: By removing the -d argument (e.g. docker run -p 9000:9000 jatos/jatos:latest) you get JATOS' logs printed in your shell - although you don't run it in detached mode in the background anymore.

    Troubleshooting 2nd: Although usually not necessary maybe you want to have a look into the running container and start a Bash terminal:

    docker exec -it running-jatos-container-id /bin/bash

    Change port​

    With Docker you can easily change JATOS' port (actually we change the port mapping of JATOS' docker container). Just use Docker -p argument and specify your port. E.g. to run JATOS on standard HTTP port 80 use:

    docker run -d -p 80:9000 jatos/jatos:latest

    Configure with environment variables​

    All environment variables that can be used to configure a normal JATOS server installation 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 a host with the IP 172.17.0.2 and with the default port 3306 use the following command (change username and password of your MySQL account):

    docker run -e JATOS_DB_URL='jdbc:mysql://172.17.0.2/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC' -e JATOS_DB_USERNAME='root' -e JATOS_DB_PASSWORD='password' -e JATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver -e JATOS_JPA=mysqlPersistenceUnit -p 9000:9000 jatos/jatos:latest
    + \ No newline at end of file diff --git a/3.7.x/Installation.html b/3.7.x/Installation.html index 4d21cc699..045f164b8 100644 --- a/3.7.x/Installation.html +++ b/3.7.x/Installation.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.7.x

    Installation

    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 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) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
      • Without Java: jatos.zip
      • Bundled with Java: jatos_win_java.zip
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
      • Without Java: jatos.zip
      • For MacOS bundled with Java: jatos_mac_java.zip
      • For Linux bundled with Java: jatos_linux_java.zip
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. All set! Now go to the browser of your choice and open 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 and play around with it.

    - +If you don't have Java installed, you can either download and install it (e.g. from adoptium.net) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. All set! Now go to the browser of your choice and open 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 and play around with it.

    + \ No newline at end of file diff --git a/3.7.x/JATOS-Tryout-Server.html b/3.7.x/JATOS-Tryout-Server.html index 5a48fd93b..624ca6fea 100644 --- a/3.7.x/JATOS-Tryout-Server.html +++ b/3.7.x/JATOS-Tryout-Server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    - +
    Skip to main content
    Version: 3.7.x

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    + \ No newline at end of file diff --git a/3.7.x/JATOS-in-Amazons-Cloud-without-Docker.html b/3.7.x/JATOS-in-Amazons-Cloud-without-Docker.html index 1c586158d..f0292b239 100644 --- a/3.7.x/JATOS-in-Amazons-Cloud-without-Docker.html +++ b/3.7.x/JATOS-in-Amazons-Cloud-without-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache you have to configure IP and port in conf/production.conf: Use the 'Private IP' from your instance description (the one that starts with 172.x.x.x) and port 80
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    - +
    Skip to main content
    Version: 3.7.x

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache you have to configure IP and port in conf/production.conf: Use the 'Private IP' from your instance description (the one that starts with 172.x.x.x) and port 80
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    + \ No newline at end of file diff --git a/3.7.x/JATOS-on-DigitalOcean.html b/3.7.x/JATOS-on-DigitalOcean.html index 3f7f73efe..a23dea9dd 100644 --- a/3.7.x/JATOS-on-DigitalOcean.html +++ b/3.7.x/JATOS-on-DigitalOcean.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    JATOS on DigitalOcean

    On this page we want to explain how to install JATOS on a server running on DigitalOcean. We tried to keep this tutorial as easy as possible: if everything runs smoothly you don't have to use the terminal at all.

    DigitalOcean is a cloud provider (like AWS, Google Cloud, Azure etc.) that is comparatively easy to use and has good documentation. They offer something called Droplets and One-Click Apps which is just a fancy name for a pre-installed server in the cloud. And btw. we have no connections to DigitalOcean whatsoever.

    Keep in mind: A server in the cloud will cost money (depending on the size $5 to $50 / month) and you will need a credit card.

    Setup a simple JATOS server on DigitalOcean​

    First we want to set up a simple JATOS server without encryption (HTTPS) or a domain name.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Use this link to create a Droplet with Docker on Ubuntu pre-installed. Do not press Create yet - we need to set up things first.

      Selected Marketplace with Docker on Ubuntu

      Your sreen should look similar to this one: Selected Marketplace with Docker x.x.x on Ubuntu x.x

    3. Scroll down to Choose a plan: Droplet size depends on your experiments. Shared CPU that come with the Basic plan are usually enough (and cheaper). For the CPU options: Memory is often the scarce resource: Common numbers are 1GB, 2GB, 4GB for a single researcher or group - or 8GB for an institutional server. If you are not sure get the smaller one - you can always scale up later. If you just want to try it out: Regular Intel with 1GB for (currently) $5/month will do it.

    4. Scroll down to Choose a datacenter region: You can actually use any you want, but best is to choose one that is near to your participants to reduce loading time.

    5. Select additional options: Here activate User Data and copy+paste the following script in the text field:

      #!/bin/bash

      # Run JATOS as docker container
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      Droplet&#39;s User Data

      The User Data should look similar to this screenshot here

    6. You could also add an SSH key under Authentication / SSH keys. If you don't know what this is, set a Password. Keep the password somewhere safe. You will need it if you ever want to log into your server's terminal.

    7. [Optional] Add backups

    8. Finally click the Create button

    9. Try out your JATOS: Now the server is being created which can take a couple seconds (or 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.

    10. Log into JATOS with ‘admin’ and password ‘admin’

    11. The first thing you should do is change your admin password:

      1. Click on ‘Admin (admin) in top-right header
      2. Click ‘Change Password’

    Voila, you have your own JATOS server.

    DigitalOcean charges you by second. So if you want to create a new JATOS server because something went wrong, just Destroy the old one and start over.

    Although usually not necessary, you can also access your server via SSH: ssh root@xx.xx.xx.xx (exchange xx.xx.xx.xx with your IP). Use the password you entered during creation of the Droplet. The first time you will be asked to change your password.

    Deleting your server​

    Deleting the server is straightforward. In DigitalOcean, go to your Droplet -> in the left menu of your Droplet choose Destroy.

    Now, you might want to use a nicer address than an IP and add some encryption-safety with HTTPS to your server - then read on.

    Add HTTPS with Traefik and use your own domain name​

    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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source and free to use.

    Buy 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. 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.

    To create a JATOS server with Traefik follow the instructions of the first paragraph (Setup a simple JATOS server on DigitalOcean) but in the User Data field of Select additional options put the following script:

    #!/bin/bash

    DOMAIN_NAME="my.domain.name"
    EMAIL="my.email@foo.com"

    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/docker-compose.yaml > /root/docker-compose.yaml
    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/traefik.toml > /root/traefik.toml

    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/docker-compose.yaml
    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/traefik.toml
    sed -i "s/<EMAIL>/${EMAIL}/g" /root/traefik.toml

    touch /root/acme.json
    chmod 600 /root/acme.json
    docker network create proxy
    docker-compose -f /root/docker-compose.yaml up -d

    Exchange my.domain.name and my.email@foo.com with your own domain name and email address. Your email we need for encryption with Let's Encrypt.

    This script downloads two config files, one for Traefik and one for Docker Compose. If you are interested you can examine them under https://github.com/JATOS/JATOS/blob/main/deploy/docker-compose.yaml and https://github.com/JATOS/JATOS/blob/main/deploy/traefik.toml. Docker Compose will start JATOS' and Traefik's container for us.

    After you've created your Droplet you still have to point your domain name to your server's IP address. This involves dealing with things like A records or AAAA records or DNS servers and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Then as a last step, after your domain name points to your server's IP, you have to reset your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and use HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption on your domain name.

    - +
    Skip to main content
    Version: 3.7.x

    JATOS on DigitalOcean

    On this page we want to explain how to install JATOS on a server running on DigitalOcean. We tried to keep this tutorial as easy as possible: if everything runs smoothly you don't have to use the terminal at all.

    DigitalOcean is a cloud provider (like AWS, Google Cloud, Azure etc.) that is comparatively easy to use and has good documentation. They offer something called Droplets and One-Click Apps which is just a fancy name for a pre-installed server in the cloud. And btw. we have no connections to DigitalOcean whatsoever.

    Keep in mind: A server in the cloud will cost money (depending on the size $5 to $50 / month) and you will need a credit card.

    Setup a simple JATOS server on DigitalOcean​

    First we want to set up a simple JATOS server without encryption (HTTPS) or a domain name.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Use this link to create a Droplet with Docker on Ubuntu pre-installed. Do not press Create yet - we need to set up things first.

      Selected Marketplace with Docker on Ubuntu

      Your sreen should look similar to this one: Selected Marketplace with Docker x.x.x on Ubuntu x.x

    3. Scroll down to Choose a plan: Droplet size depends on your experiments. Shared CPU that come with the Basic plan are usually enough (and cheaper). For the CPU options: Memory is often the scarce resource: Common numbers are 1GB, 2GB, 4GB for a single researcher or group - or 8GB for an institutional server. If you are not sure get the smaller one - you can always scale up later. If you just want to try it out: Regular Intel with 1GB for (currently) $5/month will do it.

    4. Scroll down to Choose a datacenter region: You can actually use any you want, but best is to choose one that is near to your participants to reduce loading time.

    5. Select additional options: Here activate User Data and copy+paste the following script in the text field:

      #!/bin/bash

      # Run JATOS as docker container
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      Droplet&#39;s User Data

      The User Data should look similar to this screenshot here

    6. You could also add an SSH key under Authentication / SSH keys. If you don't know what this is, set a Password. Keep the password somewhere safe. You will need it if you ever want to log into your server's terminal.

    7. [Optional] Add backups

    8. Finally click the Create button

    9. Try out your JATOS: Now the server is being created which can take a couple seconds (or 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.

    10. Log into JATOS with ‘admin’ and password ‘admin’

    11. The first thing you should do is change your admin password:

      1. Click on ‘Admin (admin) in top-right header
      2. Click ‘Change Password’

    Voila, you have your own JATOS server.

    DigitalOcean charges you by second. So if you want to create a new JATOS server because something went wrong, just Destroy the old one and start over.

    Although usually not necessary, you can also access your server via SSH: ssh root@xx.xx.xx.xx (exchange xx.xx.xx.xx with your IP). Use the password you entered during creation of the Droplet. The first time you will be asked to change your password.

    Deleting your server​

    Deleting the server is straightforward. In DigitalOcean, go to your Droplet -> in the left menu of your Droplet choose Destroy.

    Now, you might want to use a nicer address than an IP and add some encryption-safety with HTTPS to your server - then read on.

    Add HTTPS with Traefik and use your own domain name​

    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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source and free to use.

    Buy 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. 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.

    To create a JATOS server with Traefik follow the instructions of the first paragraph (Setup a simple JATOS server on DigitalOcean) but in the User Data field of Select additional options put the following script:

    #!/bin/bash

    DOMAIN_NAME="my.domain.name"
    EMAIL="my.email@foo.com"

    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/docker-compose.yaml > /root/docker-compose.yaml
    curl https://raw.githubusercontent.com/JATOS/JATOS/main/deploy/traefik.toml > /root/traefik.toml

    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/docker-compose.yaml
    sed -i "s/<DOMAIN_NAME>/${DOMAIN_NAME}/g" /root/traefik.toml
    sed -i "s/<EMAIL>/${EMAIL}/g" /root/traefik.toml

    touch /root/acme.json
    chmod 600 /root/acme.json
    docker network create proxy
    docker-compose -f /root/docker-compose.yaml up -d

    Exchange my.domain.name and my.email@foo.com with your own domain name and email address. Your email we need for encryption with Let's Encrypt.

    This script downloads two config files, one for Traefik and one for Docker Compose. If you are interested you can examine them under https://github.com/JATOS/JATOS/blob/main/deploy/docker-compose.yaml and https://github.com/JATOS/JATOS/blob/main/deploy/traefik.toml. Docker Compose will start JATOS' and Traefik's container for us.

    After you've created your Droplet you still have to point your domain name to your server's IP address. This involves dealing with things like A records or AAAA records or DNS servers and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Then as a last step, after your domain name points to your server's IP, you have to reset your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and use HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption on your domain name.

    + \ No newline at end of file diff --git a/3.7.x/JATOS-on-a-server.html b/3.7.x/JATOS-on-a-server.html index fcaf78752..aef42d262 100644 --- a/3.7.x/JATOS-on-a-server.html +++ b/3.7.x/JATOS-on-a-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    You can also install JATOS via Docker.

    Installation on a server​

    The actual JATOS instance on a server isn't too different from a local one. It basically involves telling JATOS which IP address and port it should use and (optionally) replace the embedded database with a MySQL one. There are other issues however, not directly related to JATOS, that you should consider when setting up a server. These include: setting up automatic, regular backups of your data, an automatic restart of JATOS after a server reboot, encryption, additional HTTP server, etc.

    1. Install Java​

    We've produced multiple versions of JATOS. The simplest version is JATOS alone, but other versions are bundled with Java JRE. On a server, it's best (though not necessary) to install JATOS without a bundled Java. This will make it easier to upgrade to new Java releases. Both Java 8 and 11 are fine.

    2. [Optional] Install MySQL​

    See JATOS with MySQL

    3. Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Check that JATOS starts with:

      ./loader.sh start`

      And to stop it:

      ./loader.sh stop`

    4. Configuration​

    If JATOS runs locally it's usually not necessary to change the defaults but on a server you probably want to set up the IP and port or maybe use a different database and change the path of the study assets root folder. These docs have an extra page on how to Configure JATOS on a Server.

    5. Change Admin's password​

    Every JATOS installation comes with an Admin user that has the default password 'admin'. It is highly recommended to change it before the server goes live. This can be done in JATOS' GUI:

    1. Start JATOS and in a browser go to JATOS login page http://my-jatos-domain/jatos
    2. Login as 'admin' with password 'admin'
    3. Click on 'Admin (admin)' in top-right header
    4. Click 'Change Password'

    6. Check JATOS' test page​

    JATOS comes with a handy test page: in the browser go to http://my-jatos-domain/jatos/admin, then click Tests and check that all tests are 'OK'.

    7. [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    8. [Optional] Turn on user session validation​

    More here.

    9. [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    10. [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularily.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to turn off JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    What has to be backed up in detail:

    1. Database

      • MySQL - If you use a MySQL database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.
      • H2 - There are at least two ways: one easy (but unofficial) and one official:
        1. Copy & paste the db file - It's important to stop JATOS before doing a backup or restoring a H2 database this way. If you do not stop JATOS your data might be corrupted. You can just backup the folder my-jatos-path/database.
        2. Via H2's upgrade, backup, and restore tool

    2. study_assets_root folder - This is the folder where all the study's assets (e.g. HTML, JS, CSS, images) are stored.

    3. result_uploads folder - This folder contains the files, that were uploaded during study runs.

    4. study_logs folder - Contains the study logs.

    - +
    Skip to main content
    Version: 3.7.x

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    You can also install JATOS via Docker.

    Installation on a server​

    The actual JATOS instance on a server isn't too different from a local one. It basically involves telling JATOS which IP address and port it should use and (optionally) replace the embedded database with a MySQL one. There are other issues however, not directly related to JATOS, that you should consider when setting up a server. These include: setting up automatic, regular backups of your data, an automatic restart of JATOS after a server reboot, encryption, additional HTTP server, etc.

    1. Install Java​

    We've produced multiple versions of JATOS. The simplest version is JATOS alone, but other versions are bundled with Java JRE. On a server, it's best (though not necessary) to install JATOS without a bundled Java. This will make it easier to upgrade to new Java releases. Both Java 8 and 11 are fine.

    2. [Optional] Install MySQL​

    See JATOS with MySQL

    3. Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Check that JATOS starts with:

      ./loader.sh start`

      And to stop it:

      ./loader.sh stop`

    4. Configuration​

    If JATOS runs locally it's usually not necessary to change the defaults but on a server you probably want to set up the IP and port or maybe use a different database and change the path of the study assets root folder. These docs have an extra page on how to Configure JATOS on a Server.

    5. Change Admin's password​

    Every JATOS installation comes with an Admin user that has the default password 'admin'. It is highly recommended to change it before the server goes live. This can be done in JATOS' GUI:

    1. Start JATOS and in a browser go to JATOS login page http://my-jatos-domain/jatos
    2. Login as 'admin' with password 'admin'
    3. Click on 'Admin (admin)' in top-right header
    4. Click 'Change Password'

    6. Check JATOS' test page​

    JATOS comes with a handy test page: in the browser go to http://my-jatos-domain/jatos/admin, then click Tests and check that all tests are 'OK'.

    7. [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    8. [Optional] Turn on user session validation​

    More here.

    9. [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    10. [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularily.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to turn off JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    What has to be backed up in detail:

    1. Database

      • MySQL - If you use a MySQL database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.
      • H2 - There are at least two ways: one easy (but unofficial) and one official:
        1. Copy & paste the db file - It's important to stop JATOS before doing a backup or restoring a H2 database this way. If you do not stop JATOS your data might be corrupted. You can just backup the folder my-jatos-path/database.
        2. Via H2's upgrade, backup, and restore tool

    2. study_assets_root folder - This is the folder where all the study's assets (e.g. HTML, JS, CSS, images) are stored.

    3. result_uploads folder - This folder contains the files, that were uploaded during study runs.

    4. study_logs folder - Contains the study logs.

    + \ No newline at end of file diff --git a/3.7.x/JATOS-with-Apache.html b/3.7.x/JATOS-with-Apache.html index 48efb9f62..1b9cc0bc4 100644 --- a/3.7.x/JATOS-with-Apache.html +++ b/3.7.x/JATOS-with-Apache.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    JATOS with Apache

    This is an example of a configuration of Apache as a 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 allow encryption.

    Here I used Apache 2.4.18 on a Ubuntu system. It is necessary to use at least version 2.4 since JATOS relies on WebSockets that aren't supported by earlier Apache versions.

    A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is certbot.eff.org from the Electronic Frontier Foundation.

    I had to add some modules to Apache to get it working:

    sudo a2enmod rewrite
    sudo a2enmod proxy_wstunnel
    sudo a2enmod proxy
    sudo a2enmod headers
    sudo a2enmod ssl
    sudo a2enmod lbmethod_byrequests
    sudo a2enmod proxy_balancer
    sudo a2enmod proxy_http
    sudo a2enmod remoteip

    The following is an example of a proxy config with Apache. I stored it in /etc/apache2/sites-available/example.com.conf and added it to Apache with the command sudo a2ensite example.com.conf.

    • It enforces access via HTTPS by redirecting all HTTP traffic.
    • 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.
    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # Needed for JATOS to get the correct host and protocol
      ProxyPreserveHost On
      RequestHeader set X-Forwarded-Proto "https"
      RequestHeader set X-Forwarded-Ssl "on"
      
      # 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/
    </VirtualHost>
    - +
    Skip to main content
    Version: 3.7.x

    JATOS with Apache

    This is an example of a configuration of Apache as a 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 allow encryption.

    Here I used Apache 2.4.18 on a Ubuntu system. It is necessary to use at least version 2.4 since JATOS relies on WebSockets that aren't supported by earlier Apache versions.

    A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is certbot.eff.org from the Electronic Frontier Foundation.

    I had to add some modules to Apache to get it working:

    sudo a2enmod rewrite
    sudo a2enmod proxy_wstunnel
    sudo a2enmod proxy
    sudo a2enmod headers
    sudo a2enmod ssl
    sudo a2enmod lbmethod_byrequests
    sudo a2enmod proxy_balancer
    sudo a2enmod proxy_http
    sudo a2enmod remoteip

    The following is an example of a proxy config with Apache. I stored it in /etc/apache2/sites-available/example.com.conf and added it to Apache with the command sudo a2ensite example.com.conf.

    • It enforces access via HTTPS by redirecting all HTTP traffic.
    • 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.
    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # Needed for JATOS to get the correct host and protocol
      ProxyPreserveHost On
      RequestHeader set X-Forwarded-Proto "https"
      RequestHeader set X-Forwarded-Ssl "on"
      
      # 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/
    </VirtualHost>
    + \ No newline at end of file diff --git a/3.7.x/JATOS-with-MySQL.html b/3.7.x/JATOS-with-MySQL.html index 8b273e50a..93e45346d 100644 --- a/3.7.x/JATOS-with-MySQL.html +++ b/3.7.x/JATOS-with-MySQL.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    JATOS with MySQL

    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 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 (although we had no problems with H2 so far)

    Installation​

    One could install the external database on the same server as JATOS is running or on an extra server depending on ones need.

    There are many manuals out there, e.g. this one. One way to set up MySQL:

    1. Install MySQL, e.g. on Ubuntu

      JATOS requires MySQL >= 5.7 (8.x is fine)

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword';

      Remember your username and password. You need them when configuring JATOS later on.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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.

    Configure JATOS​

    There are three ways to set up JATOS to work with a MySQL database. If you are in doubt use 'production.conf'.

    1. Via JATOS config file which is in your JATOS folder in the conf folder: conf/production.conf

      Change IP, port, username and password to your needs.

      db.default.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      db.default.user="jatosuser"
      db.default.password="mypassword"
      db.default.driver=com.mysql.cj.jdbc.Driver

      Always restart JATOS after making any changes to the configuration (e.g. with ./loader.sh restart)

    2. Via command-line arguments:

      • -DJATOS_DB_URL - specifies the URL to the database
      • -DJATOS_DB_USERNAME - set your username
      • -DJATOS_DB_PASSWORD - set your password
      • -DJATOS_DB_DRIVER - always com.mysql.cj.jdbc.Driver for MySQL

      E.g. to connect to a MySQL running on 127.0.0.1 and port 3306 use (but change username and password):

      ./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=sa -DJATOS_DB_PASSWORD=sa -DJATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver

    3. Via environment variables (change IP, port, username and password)

      export JATOS_DB_URL="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      export JATOS_DB_USERNAME=jatosuser
      export JATOS_DB_PASSWORD='mypassword'
      export 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.

    Done. Your JATOS uses your MySQL now.

    [Optional] Deactivate MySQL's binary log​

    MySQL's binary logs (also called binlogs) serve two purposes: replication and data recovery. More can be found in MySQLs documentation.

    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's config but on many systems they are under /var/lib/mysql. If you have a single MySQL instance (and therefore do not use replication) and you do not need MySQL's 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 config (details). 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:

    # 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 for the changes to take effect.

    [Optional] Increase 'max_allowed_packet' size in older MySQLs​

    If you have an older MySQL (< 8.x.x) and your experiments will have large resut data you might want to increase the '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

    From 8.x.x the 'max_allowed_packet' is by default 64MB and this is usually more than enough. But in version smaller than 8.x.x 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 config. On many Linux systems the config is in /etc/mysql/mysql.conf.d/mysqld.cnf. E.g. to set it to 64MB:

    max_allowed_packet=64M

    You have to restart MySQL for the changes to take effect.

    - +
    Skip to main content
    Version: 3.7.x

    JATOS with MySQL

    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 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 (although we had no problems with H2 so far)

    Installation​

    One could install the external database on the same server as JATOS is running or on an extra server depending on ones need.

    There are many manuals out there, e.g. this one. One way to set up MySQL:

    1. Install MySQL, e.g. on Ubuntu

      JATOS requires MySQL >= 5.7 (8.x is fine)

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword';

      Remember your username and password. You need them when configuring JATOS later on.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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.

    Configure JATOS​

    There are three ways to set up JATOS to work with a MySQL database. If you are in doubt use 'production.conf'.

    1. Via JATOS config file which is in your JATOS folder in the conf folder: conf/production.conf

      Change IP, port, username and password to your needs.

      db.default.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      db.default.user="jatosuser"
      db.default.password="mypassword"
      db.default.driver=com.mysql.cj.jdbc.Driver

      Always restart JATOS after making any changes to the configuration (e.g. with ./loader.sh restart)

    2. Via command-line arguments:

      • -DJATOS_DB_URL - specifies the URL to the database
      • -DJATOS_DB_USERNAME - set your username
      • -DJATOS_DB_PASSWORD - set your password
      • -DJATOS_DB_DRIVER - always com.mysql.cj.jdbc.Driver for MySQL

      E.g. to connect to a MySQL running on 127.0.0.1 and port 3306 use (but change username and password):

      ./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=sa -DJATOS_DB_PASSWORD=sa -DJATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver

    3. Via environment variables (change IP, port, username and password)

      export JATOS_DB_URL="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"
      export JATOS_DB_USERNAME=jatosuser
      export JATOS_DB_PASSWORD='mypassword'
      export 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.

    Done. Your JATOS uses your MySQL now.

    [Optional] Deactivate MySQL's binary log​

    MySQL's binary logs (also called binlogs) serve two purposes: replication and data recovery. More can be found in MySQLs documentation.

    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's config but on many systems they are under /var/lib/mysql. If you have a single MySQL instance (and therefore do not use replication) and you do not need MySQL's 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 config (details). 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:

    # 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 for the changes to take effect.

    [Optional] Increase 'max_allowed_packet' size in older MySQLs​

    If you have an older MySQL (< 8.x.x) and your experiments will have large resut data you might want to increase the '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

    From 8.x.x the 'max_allowed_packet' is by default 64MB and this is usually more than enough. But in version smaller than 8.x.x 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 config. On many Linux systems the config is in /etc/mysql/mysql.conf.d/mysqld.cnf. E.g. to set it to 64MB:

    max_allowed_packet=64M

    You have to restart MySQL for the changes to take effect.

    + \ No newline at end of file diff --git a/3.7.x/JATOS-with-Nginx.html b/3.7.x/JATOS-with-Nginx.html index 750a13760..7528efba8 100644 --- a/3.7.x/JATOS-with-Nginx.html +++ b/3.7.x/JATOS-with-Nginx.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    JATOS with Nginx

    These are examples for configurations of Nginx as a proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common. They support WebSockets for JATOS' group studies.

    The following two configs are the content of /etc/nginx/nginx.conf. Change them 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. This proxy_set_header X-Forwarded-* is necessary to tell JATOS the original requester's IP address - please leave it unchanged.

    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.

    A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is certbot.eff.org from the Electronic Frontier Foundation.

    With HTTPS​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;
    include /etc/nginx/modules-enabled/*.conf;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile             on;
            tcp_nopush           on;
            tcp_nodelay          on;
            keepalive_timeout    65;
            client_max_body_size 500M;

            include      /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto https;
            proxy_set_header   X-Forwarded-Ssl on;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            # redirect http to https
            server {
                    listen      80;
                    server_name www.example.com;
                    rewrite     ^ https://www.example.com$request_uri? permanent;
            }

            server {
                    listen        443 ssl;
                    server_name   www.example.com;

                    keepalive_timeout    70;

                    ssl_certificate      /etc/ssl/certs/localhost.crt;
                    ssl_certificate_key  /etc/ssl/private/localhost.key;

                    ssl_protocols             TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
                    ssl_prefer_server_ciphers on;

                    # 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 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;
                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }

    With HTTPS and Docker​

    Have a look at github.com/robinsonkwame/jatos-https-docker-compose for a good example in how to do this (Thanks to Kwame Porter Robinson)

    Simple without encryption​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile on;
            keepalive_timeout 65;
            client_max_body_size 500M;

            include /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto http;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            server {
                    listen               80;

                    keepalive_timeout    70;
                    server_name          www.example.com;

                    # 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
                    #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;

                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }
    - +
    Skip to main content
    Version: 3.7.x

    JATOS with Nginx

    These are examples for configurations of Nginx as a proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common. They support WebSockets for JATOS' group studies.

    The following two configs are the content of /etc/nginx/nginx.conf. Change them 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. This proxy_set_header X-Forwarded-* is necessary to tell JATOS the original requester's IP address - please leave it unchanged.

    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.

    A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is certbot.eff.org from the Electronic Frontier Foundation.

    With HTTPS​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;
    include /etc/nginx/modules-enabled/*.conf;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile             on;
            tcp_nopush           on;
            tcp_nodelay          on;
            keepalive_timeout    65;
            client_max_body_size 500M;

            include      /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto https;
            proxy_set_header   X-Forwarded-Ssl on;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            # redirect http to https
            server {
                    listen      80;
                    server_name www.example.com;
                    rewrite     ^ https://www.example.com$request_uri? permanent;
            }

            server {
                    listen        443 ssl;
                    server_name   www.example.com;

                    keepalive_timeout    70;

                    ssl_certificate      /etc/ssl/certs/localhost.crt;
                    ssl_certificate_key  /etc/ssl/private/localhost.key;

                    ssl_protocols             TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
                    ssl_prefer_server_ciphers on;

                    # 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 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;
                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }

    With HTTPS and Docker​

    Have a look at github.com/robinsonkwame/jatos-https-docker-compose for a good example in how to do this (Thanks to Kwame Porter Robinson)

    Simple without encryption​

    user www-data;
    worker_processes auto;
    pid /run/nginx.pid;

    events {
            worker_connections 768;
            # multi_accept on;
    }

    http {
            sendfile on;
            keepalive_timeout 65;
            client_max_body_size 500M;

            include /etc/nginx/mime.types;
            default_type application/octet-stream;

            proxy_buffering    off;
            proxy_set_header   X-Forwarded-Proto http;
            proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header   Host $http_host;
            proxy_http_version 1.1;

            upstream jatos-backend {
                    server 127.0.0.1:9000;
            }

            # needed for websockets
            map $http_upgrade $connection_upgrade {
                    default upgrade;
                    ''      close;
            }

            server {
                    listen               80;

                    keepalive_timeout    70;
                    server_name          www.example.com;

                    # 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
                    #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;

                    }
            }

            access_log /var/log/nginx/access.log;
            error_log /var/log/nginx/error.log;

            include /etc/nginx/conf.d/*.conf;
            #include /etc/nginx/sites-enabled/*;
    }
    + \ No newline at end of file diff --git a/3.7.x/Manage-Results.html b/3.7.x/Manage-Results.html index 963c9ad12..5989d5615 100644 --- a/3.7.x/Manage-Results.html +++ b/3.7.x/Manage-Results.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Manage Results

    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

    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

    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

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export​

    Export Result Data​

    Once you selected the results you're interested in, click Export Results and Selected and you will download a text file that contains your results. Each line in this text file represents result data from one component. Alternatively you can also select All to get all result data.

    Results View screenshot

    Export Result Files​

    Here you can download the result files that were uploaded during study runs. You can download single files by just clicking on them. Or similar to exporting result data select the lines you are interested in and download them with Export Files and Selected. Alternatively you can also select All to get all files.

    Results View screenshot

    Export Metadata​

    Sometimes one is also interested in the metadata, that is what's in the actual table fields ("Result ID", "Start Time" , "Last Seen", ...). For this click on Export Metadata and the metadata of the selected results will be downloaded in CSV format.

    Results View screenshot

    Delete Results​

    You can click Delete to remove all or only some selected results (result data + result files + metadata). Keep in mind there's no undo function for this.

    Results View screenshot

    Table Columns​

    You can show and hide the columns displayed in the table with the drop-down menu under the Customize button.

    Results View screenshot

    • 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 (set at the server's time zone) at which the first component of the study was started.

    • End Time - Time (set at the server's time zone) 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.

    • 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 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 (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 or jatos.abortStudy.

    - +
    Skip to main content
    Version: 3.7.x

    Manage Results

    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

    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

    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

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export​

    Export Result Data​

    Once you selected the results you're interested in, click Export Results and Selected and you will download a text file that contains your results. Each line in this text file represents result data from one component. Alternatively you can also select All to get all result data.

    Results View screenshot

    Export Result Files​

    Here you can download the result files that were uploaded during study runs. You can download single files by just clicking on them. Or similar to exporting result data select the lines you are interested in and download them with Export Files and Selected. Alternatively you can also select All to get all files.

    Results View screenshot

    Export Metadata​

    Sometimes one is also interested in the metadata, that is what's in the actual table fields ("Result ID", "Start Time" , "Last Seen", ...). For this click on Export Metadata and the metadata of the selected results will be downloaded in CSV format.

    Results View screenshot

    Delete Results​

    You can click Delete to remove all or only some selected results (result data + result files + metadata). Keep in mind there's no undo function for this.

    Results View screenshot

    Table Columns​

    You can show and hide the columns displayed in the table with the drop-down menu under the Customize button.

    Results View screenshot

    • 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 (set at the server's time zone) at which the first component of the study was started.

    • End Time - Time (set at the server's time zone) 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.

    • 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 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 (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 or jatos.abortStudy.

    + \ No newline at end of file diff --git a/3.7.x/OSWeb-and-JATOS.html b/3.7.x/OSWeb-and-JATOS.html index ffffd7529..dbd00bc20 100644 --- a/3.7.x/OSWeb-and-JATOS.html +++ b/3.7.x/OSWeb-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    - +
    Skip to main content
    Version: 3.7.x

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    + \ No newline at end of file diff --git a/3.7.x/Papers-Citing-JATOS.html b/3.7.x/Papers-Citing-JATOS.html index 5d132e12d..dc4e660ad 100644 --- a/3.7.x/Papers-Citing-JATOS.html +++ b/3.7.x/Papers-Citing-JATOS.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.7.x

    Papers citing JATOS

    JATOS has been used sucessfully to collect data all over the world. Here is a curated list of peer-reviewed publications or preprints (that we are aware of) that used JATOS to collect data. (You can also see the full list of citations.)

    Please cite us 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 on how (much) you use JATOS (ca. 3 min). It’s very important for us!

    2023​

    van Moorselaar, D., & Theeuwes, J. (2023). Statistical Learning Within Objects. Psychological Science DOI

    Lu, Z., van Zoest, W. (2023) Combining social cues in attention: Looking at gaze, head, and pointing cues. Atten Percept Psychophys. DOI

    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

    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

    Reichardt, R., Polner, B., & Simor, P. (2023). Influencing prior knowledge through a short reading impacts curiosity and learning. Applied Cognitive Psychology DOI

    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

    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

    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

    Lee, M.D., Stark, C.E.L. (2023) Bayesian modeling of the Mnemonic Similarity Task using multinomial processing trees. Behaviormetrika DOI

    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

    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

    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

    Zoefel B, Gilbert RA, Davis MH (2023) Intelligibility improves perception of timing changes in speech. PLoS ONE DOI

    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

    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

    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

    2022​

    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

    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

    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

    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

    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

    Zoefel, B., Gilbert, R. A., & Davis, M. H. (2022). Intelligibility improves perception of timing changes in speech. BioRxiv DOI

    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

    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

    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

    Constant, M., Pereira, M., Faivre, N., Filevich, E. (2022) Prior information differentially affects discrimination decisions and subjective confidence reports bioRxiv DOI

    Wittmann BC, Şatırer Y. (2022) Decreased associative processing and memory confidence in aphantasia. Learn Mem. DOI

    Vogt, A., Kaup, B., Abdel Rahman, R., & Ganter, I. (2022). Embodied language production: sensorimotor activations and interoceptive sensibility influence which words we choose when speaking. PsyArXiv DOI

    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

    Mueckstein, M., Heinzel, S., Granacher, U., Brahms, M., Rapp, MA., Stelzel, C. (2022) Modality-specific effects of mental fatigue in multitasking, Acta Psychologica DOI

    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

    Hsieh, JYJ., Boyce, P., Goddard, E. et al. (2022) Colour information biases facial age estimation and reduces inter-observer variability. PREPRINT available at Research Square, DOI

    Belo, J., Clerc, M., Schön, D. (2022) Attentional inhibition ability predicts neural representation during challenging auditory streaming. bioRxiv DOI

    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

    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

    Radović T, Rieger T and Manzey D (2022) A global and local perspective of interruption frequency in a visual search task. Front. Psychol. DOI

    Vos, M., Minor, S., & Ramchand, G. C. (2022). Comparing infrared and webcam eye tracking in the Visual World Paradigm. Glossa Psycholinguistics DOI

    Tsang, K. Y., & Mannion, D. J. (2022). Relating Sound and Sight in Simulated Environments. Multisensory Research DOI

    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

    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

    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

    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

    Contemori, G., Saccani, MS., Bonato, M. (2022) Multitasking Effects on Perceptionand Memory in Older Adults. Vision DOI

    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

    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

    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

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    Del Popolo Cristaldi, F., Buodo, G., Gambarota, F., Oosterwijk, S., & Mento, G. (2021, December 16). The role of implicit learning and cue ambiguity on the subjective experience of affective predictions: a follow-up behavioral investigation. PsyArXiv DOI

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Del Popolo Cristaldi, F., Gambarota, F., & Oosterwijk, S. (2021). The role of previous visual experience in subjective reactions to new affective pictures and sounds. PsyArXiv DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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.

    Kumbhar, O., Sizikova, E., Majaj, N., & Pelli, D. G. (2020). Anytime Prediction as a Model of Human Reaction Time. ArXiv2011.12859(Cs, q-Bio). DOI

    Vari, J. & Tamburelli, M. (2020) Standardisation: bolstering positive attitudes towards endangered language varieties? Evidence from implicit attitudes. Journal of Multilingual and Multicultural Development. DOI

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    - +Language Sciences DOI

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    Del Popolo Cristaldi, F., Buodo, G., Gambarota, F., Oosterwijk, S., & Mento, G. (2021, December 16). The role of implicit learning and cue ambiguity on the subjective experience of affective predictions: a follow-up behavioral investigation. PsyArXiv DOI

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Del Popolo Cristaldi, F., Gambarota, F., & Oosterwijk, S. (2021). The role of previous visual experience in subjective reactions to new affective pictures and sounds. PsyArXiv DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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.

    Kumbhar, O., Sizikova, E., Majaj, N., & Pelli, D. G. (2020). Anytime Prediction as a Model of Human Reaction Time. ArXiv2011.12859(Cs, q-Bio). DOI

    Vari, J. & Tamburelli, M. (2020) Standardisation: bolstering positive attitudes towards endangered language varieties? Evidence from implicit attitudes. Journal of Multilingual and Multicultural Development. DOI

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    + \ No newline at end of file diff --git a/3.7.x/Restricting-study-flow.html b/3.7.x/Restricting-study-flow.html index ad5e4321c..2c13a3c55 100644 --- a/3.7.x/Restricting-study-flow.html +++ b/3.7.x/Restricting-study-flow.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Restricting study flow - reloading, linear studies, single-use workers and previews

    Intro: Restricting study flow​

    Let's first say what we understand under the study flow:

    Study flow - the intended order of a study's componenents 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

    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

    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 and about study links.

    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

    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.

    - +
    Skip to main content
    Version: 3.7.x

    Restricting study flow - reloading, linear studies, single-use workers and previews

    Intro: Restricting study flow​

    Let's first say what we understand under the study flow:

    Study flow - the intended order of a study's componenents 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

    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

    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 and about study links.

    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

    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.

    + \ No newline at end of file diff --git a/3.7.x/Run-an-experiment-with-JATOS-Workflow.html b/3.7.x/Run-an-experiment-with-JATOS-Workflow.html index 3f636b189..48af807d5 100644 --- a/3.7.x/Run-an-experiment-with-JATOS-Workflow.html +++ b/3.7.x/Run-an-experiment-with-JATOS-Workflow.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.7.x

    Run an experiment with JATOS - Workflow

    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

    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. -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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    - +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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    + \ No newline at end of file diff --git a/3.7.x/Run-your-Study-with-Study-Links.html b/3.7.x/Run-your-Study-with-Study-Links.html index c8e187426..b154d1653 100644 --- a/3.7.x/Run-your-Study-with-Study-Links.html +++ b/3.7.x/Run-your-Study-with-Study-Links.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Run your Study with Study Links

    Study Links in JATOS is the name of a page where one can generate study links for your particpants to run your study. You can also organize your participants into batches and handle their results there. In earlier versions of JATOS it was called Worker and Batch Manager.

    To get to the Study Links page press on the button with the same name in your study's page:

    Study Links Button screenshot

    This Study Links page has only one batch, the 'Default' one. A batch can have study links of different type, e.g. Personal Single, Personal Multiple etc:

    Study Links page screenshot

    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.

    Study Links page screenshot

    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

    You can de-/activate a study link type by clicking in the checkboxes in the left of each row (red box). Decactived types cannot be used to run a study. Always check before you send out study links that the corresponding types are activated.

    Study Links page screenshot

    Personal type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    1. This button creates one study link without a comment. This button is a shortcut to the 'New Study Links' button.
    2. 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 destinguish your study links. You can create Personal type study links in bulk by changing the Amount value.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. 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).

    Study Links page screenshot

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and create study links is described in its own page: Connect to Mechanical Turk.

    Study Entry Page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    If you toogle 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

    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 curiousity) 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

    The advantage of using the Study Entry page with the study codes is similar to a 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

    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

    • 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 a JSON input similar to the one in the study or component properties. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    - +
    Skip to main content
    Version: 3.7.x

    Run your Study with Study Links

    Study Links in JATOS is the name of a page where one can generate study links for your particpants to run your study. You can also organize your participants into batches and handle their results there. In earlier versions of JATOS it was called Worker and Batch Manager.

    To get to the Study Links page press on the button with the same name in your study's page:

    Study Links Button screenshot

    This Study Links page has only one batch, the 'Default' one. A batch can have study links of different type, e.g. Personal Single, Personal Multiple etc:

    Study Links page screenshot

    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.

    Study Links page screenshot

    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

    You can de-/activate a study link type by clicking in the checkboxes in the left of each row (red box). Decactived types cannot be used to run a study. Always check before you send out study links that the corresponding types are activated.

    Study Links page screenshot

    Personal type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    1. This button creates one study link without a comment. This button is a shortcut to the 'New Study Links' button.
    2. 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 destinguish your study links. You can create Personal type study links in bulk by changing the Amount value.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. 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).

    Study Links page screenshot

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and create study links is described in its own page: Connect to Mechanical Turk.

    Study Entry Page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    If you toogle 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

    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 curiousity) 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

    The advantage of using the Study Entry page with the study codes is similar to a 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

    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

    • 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 a JSON input similar to the one in the study or component properties. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    + \ No newline at end of file diff --git a/3.7.x/Session-Data-Three-Types.html b/3.7.x/Session-Data-Three-Types.html index b3ffd6348..0170c6063 100644 --- a/3.7.x/Session-Data-Three-Types.html +++ b/3.7.x/Session-Data-Three-Types.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.7.x

    Session Data - Three Types

    When to use the sessions?​

    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 JSON Input Data instead.


    Comparative Overview​

    Batch SessionGroup SessionStudy Session
    Scope (accesible by)All workers in a batchAll workers in a groupAll components in a study
    UsageExchange and store data relevant for all members of a batchExchange and temporarily store data relevant for all members of a groupExchange 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 batchStore choices of the two members of a Prisoner's Dilemma gamePass on correct answers between components; Keep track of the number of iterations of a given component that is repeated
    LifetimeSurvives after all workers finished their studiesAutomatically deleted once the group is finishedDeleted once the worker finished the study - Hence temporary
    Updated when and viaAny time you call one of the jatos.batchSession functionsAny time you call one of the jatos.groupSession functionsAt the end of each component or if you call jatos.setStudySessionData
    Visible and editable from JATOS' GUIyesnono
    Requires WebSocketsyesyesno
    Included in exported studiesnonono

    Example Study​

    We have an example study, 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".

    2. Run the study once: easiest is as a JATOS worker (just click 'Run' on the study bar, not on any of the component bars).

    3. 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

    4. 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

    5. 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. 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 -Second component screenshot

    - +Second component screenshot

    + \ No newline at end of file diff --git a/3.7.x/Study-Log.html b/3.7.x/Study-Log.html index a51d13619..087212ece 100644 --- a/3.7.x/Study-Log.html +++ b/3.7.x/Study-Log.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Study Log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    - +
    Skip to main content
    Version: 3.7.x

    Study Log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    + \ No newline at end of file diff --git a/3.7.x/Submit-and-upload-data-to-the-server.html b/3.7.x/Submit-and-upload-data-to-the-server.html index 0165b7f4c..6a0948c20 100644 --- a/3.7.x/Submit-and-upload-data-to-the-server.html +++ b/3.7.x/Submit-and-upload-data-to-the-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    - +
    Skip to main content
    Version: 3.7.x

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    + \ No newline at end of file diff --git a/3.7.x/Tips-and-Tricks.html b/3.7.x/Tips-and-Tricks.html index bc9f7439e..a33e4fd8a 100644 --- a/3.7.x/Tips-and-Tricks.html +++ b/3.7.x/Tips-and-Tricks.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Tips & Tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    - +
    Skip to main content
    Version: 3.7.x

    Tips & Tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    + \ No newline at end of file diff --git a/3.7.x/Troubleshooting.html b/3.7.x/Troubleshooting.html index 372b69263..2ef0c0899 100644 --- a/3.7.x/Troubleshooting.html +++ b/3.7.x/Troubleshooting.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    - +
    Skip to main content
    Version: 3.7.x

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    + \ No newline at end of file diff --git a/3.7.x/Update-JATOS.html b/3.7.x/Update-JATOS.html index 0bbbd0cad..1cfb34c8f 100644 --- a/3.7.x/Update-JATOS.html +++ b/3.7.x/Update-JATOS.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.7.x

    Update JATOS

    If you want to update a JATOS server please read this page first.

    We'll periodically update JATOS with new features and bug fixes. We recommend you stay up to date with the latest release. However if you are currently running a study it's always safest to keep the same JATOS version throughout the whole experiment.

    You can update your JATOS automatically (if you have admin rights and running on Mac OS or Linux (including Docker), that is). Windows is not yet supported.

    Normal process​

    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

    2. We expect no problems, but we recommend that you back up your result data, result files, study assets folder and study logs before continuing.

    3. 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.

    4. After download is complete, you will be asked again for confirmation. Optionally you can do a backup: JATOS will copy the content of its own installation folder into a folder with the name backup_x.x.x (x.x.x is the version before the update). This will usually include your embedded H2 database, your study assets and logs - but not your MySQL database (should you have one). If anything goes wrong in the auto-update, you have everything in this backup folder to start the old JATOS again. This backup will use up disk space (that is why it is not selected by default).

      Update notification Schreenshot

    5. After clicking the Go on button, JATOS will stop itself, replace its program files and re-start itself again. This might take up to a minute.

    6. Refresh your JATOS home page every now and then until you see your updated JATOS' login screen again.

    7. Check the new JATOS with the build-in tests: go to Administration ⇒ Tests and check that all tests are 'OK'.

    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 wich 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.

    Specify a version​

    Sometimes, for whatever reasons, JATOS doesn't autmatically 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 parameter version can be added to the JATOS administration page's URL. It takes the version tag as specified in GitHub and enforces an update to this version. E.g. if your domain is my.jatos.org and the version you want to update to is v3.7.4 (don't forget the 'v'), than the URL for your browser is https://my.jatos.org/jatos/admin?version=v3.7.4. The rest of the update procedure is like the Normal Process: you will be ask for conirmation twice.

    Manual Update​

    To be absolutely safe you can install the new JATOS version and keep the old one untouched. This way you can switch back if something fails. Just remember that only one JATOS can run at the same time. Always stop your old JATOS instance before starting another one.

    You can update your local JATOS instance in two main ways (The procedure is a little different if you want to update JATOS on a server installation):

    First, easy way: discarding your result data​

    If you don't care about result data stored in JATOS:

    1. Export any studies you wish to keep from the old JATOS installation.
    2. Download and install the new version as if it were a new fresh download. Don't start it yet.
    3. Stop the old JATOS and start the new JATOS.
    4. 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
    2. All your studies' and components' properties
    3. The properties of the first (Default) batch

    What will be lost:

    1. All result data will be lost
    2. All workers in all batches (including Default batch)
    3. All batches other than the Default batch
    4. All study logs

    Second way: keeping everything (including your result data)​

    If you do want to keep your studies, batches, and your result data you'll have to move them to the new JATOS.

    1. Stop JATOS (on Unix systems, type ./loader.sh stop on the terminal. On Windows MS, close your command window)
    2. Go to the folder of your old JATOS installation. From there copy your assets root folder to the new JATOS installation (Note: By default your assets root folder is called study_assets_root and lays in the JATOS folder but you might have changed this. You can find the location and name in conf/production.conf. It is specified in the line beginning with jatos.studyAssetsRootPath=.)
    3. Go to the folder of your old JATOS installation. From there copy your folder of your uploaded result files to the new JATOS installation (Note: By default this folder is called result_uploads and lays in the JATOS folder but you might have changed this. You can find the location and name in conf/production.conf. It is specified in the line beginning with jatos.resultUploads.path=.)
    4. From the folder of your old JATOS installation copy the folders database and study_logs to the folder of the new JATOS installation.
    5. If you had changed the conf/production.conf file in your old JATOS instance (for example to set a custom location for your study_assets_root folder) you'll have to do this again in the new JATOS version. We recommend re-editing the new version of the file, rather than just overwriting the new with the old version, in case anything in the production.conf file has changed.
    6. Start the new JATOS (on Unix systems, type ./loader.sh start on the terminal. On Windows double click the loader.bat)
    7. Check the build-in tests: go to Administration ⇒ Tests and check that all tests are 'OK'.

    What will be transferred:

    1. Files and subfolders in study assets folder
    2. All your study and components properties
    3. All batches, together with their workers, generated links, and results
    4. All study logs

    What will be lost: -nothing

    - +nothing

    + \ No newline at end of file diff --git a/3.7.x/Updating-a-JATOS-server-installation.html b/3.7.x/Updating-a-JATOS-server-installation.html index 8e4383994..fbdddfcb1 100644 --- a/3.7.x/Updating-a-JATOS-server-installation.html +++ b/3.7.x/Updating-a-JATOS-server-installation.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Updating a JATOS server installation

    Updating the server instance is equivalent to doing it locally, but make sure that you know what you're doing; especially if you have paired JATOS with a MySQL database.

    Backup your JATOS

    The easiest way to backup is to do a snapshot of the whole server. If you use an external MySQL database with your JATOS, make a backup e.g. using mysqldump -u yourUserName -p yourDatabaseName > yourDatabaseName.out - or a snapshot of the whole database server.

    As with updating of a local JATOS installation you can do it automatically or manually.

    After updating you can check the new JATOS installation with the test page: go to Administration ⇒ Tests and check that all tests are 'OK'.

    This is the easiest way. Then it's the same as in a local installation.

    If you did a manual backup before you don't need to do the backup offered during the update process.

    Manual Update (if automatic doesn't work for you)​

    You have two ways to update manually: 1) Keep your studies but discard all your result data and batches. 2) Keep everything, including your studies and result data (might not always be possible).

    First option: quick and dirty (discarding result data)​

    You can just follow the update instructions for the local installation. If you use a MySQL database don't forget to configure it with a clean and new one (not the one from your old JATOS). Do not use the new JATOS with the old MySQL database unless you choose to keep your data, as described below.

    Second option: keeping everything​

    This means that we have to configure the MySQL database or copy the embedded H2 database files.

    1. Stop the old JATOS using ./loader.sh stop
    2. Copy the new JATOS version to your server, e.g. copy it into the same folder where your old JATOS is located. Don't yet remove the old JATOS instance.
    3. Unzip the new JATOS (unzip jatos.zip)
    4. From the old JATOS installation copy some folders to the new one
      1. Your assets root folder to the new JATOS installation (Note: By default your assets root folder is called study_assets_root and lays in the JATOS folder but you might have changed this.
      2. If exists, your folder for uploaded result files (Note: By default this folder is called result_uploads and lays in the JATOS folder but you might have changed this.
      3. If exists, study_logs
    5. Database
      • H2 - If you are using the default H2 database: From your the folder of your old JATOS installation copy the folder database to the new JATOS installation. Remember to stop JATOS before copying the folder.
      • MySQL - For MySQL you don't have to change anything on the database side.
    6. Configure the new JATOS like the old one - usually it's enough to copy the production.conf from the old conf folder into the new one
    7. Start the new JATOS using ./loader.sh start
    8. Open JATOS' test page (Administration ⇒ Tests) and check that everything is 'OK'
    - +
    Skip to main content
    Version: 3.7.x

    Updating a JATOS server installation

    Updating the server instance is equivalent to doing it locally, but make sure that you know what you're doing; especially if you have paired JATOS with a MySQL database.

    Backup your JATOS

    The easiest way to backup is to do a snapshot of the whole server. If you use an external MySQL database with your JATOS, make a backup e.g. using mysqldump -u yourUserName -p yourDatabaseName > yourDatabaseName.out - or a snapshot of the whole database server.

    As with updating of a local JATOS installation you can do it automatically or manually.

    After updating you can check the new JATOS installation with the test page: go to Administration ⇒ Tests and check that all tests are 'OK'.

    This is the easiest way. Then it's the same as in a local installation.

    If you did a manual backup before you don't need to do the backup offered during the update process.

    Manual Update (if automatic doesn't work for you)​

    You have two ways to update manually: 1) Keep your studies but discard all your result data and batches. 2) Keep everything, including your studies and result data (might not always be possible).

    First option: quick and dirty (discarding result data)​

    You can just follow the update instructions for the local installation. If you use a MySQL database don't forget to configure it with a clean and new one (not the one from your old JATOS). Do not use the new JATOS with the old MySQL database unless you choose to keep your data, as described below.

    Second option: keeping everything​

    This means that we have to configure the MySQL database or copy the embedded H2 database files.

    1. Stop the old JATOS using ./loader.sh stop
    2. Copy the new JATOS version to your server, e.g. copy it into the same folder where your old JATOS is located. Don't yet remove the old JATOS instance.
    3. Unzip the new JATOS (unzip jatos.zip)
    4. From the old JATOS installation copy some folders to the new one
      1. Your assets root folder to the new JATOS installation (Note: By default your assets root folder is called study_assets_root and lays in the JATOS folder but you might have changed this.
      2. If exists, your folder for uploaded result files (Note: By default this folder is called result_uploads and lays in the JATOS folder but you might have changed this.
      3. If exists, study_logs
    5. Database
      • H2 - If you are using the default H2 database: From your the folder of your old JATOS installation copy the folder database to the new JATOS installation. Remember to stop JATOS before copying the folder.
      • MySQL - For MySQL you don't have to change anything on the database side.
    6. Configure the new JATOS like the old one - usually it's enough to copy the production.conf from the old conf folder into the new one
    7. Start the new JATOS using ./loader.sh start
    8. Open JATOS' test page (Administration ⇒ Tests) and check that everything is 'OK'
    + \ No newline at end of file diff --git a/3.7.x/Use-Prolific.html b/3.7.x/Use-Prolific.html index b89ed7ffa..b008c9524 100644 --- a/3.7.x/Use-Prolific.html +++ b/3.7.x/Use-Prolific.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Use Prolific

    It is very easy to use JATOS together with Prolific to recruit participants.

    This is what the New Study page in Prolific looks like:

    Prolific screenshot

    In the field under What is the URL of your study? (first red box in the screenshot), 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).

    2. (Optional) 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. Click on 'Show advanced' and then 'Add parameters' like in the screenshot.

    Prolific screenshot

    Then you can access those URL parameters in your study's JavaScript via jatos.urlQueryParameters.

    3. Redirect to Prolific's end page after the study is done​

    The second red box contains a link that will (re)direct the participant to a Prolific page, with information on how to claim their payment.

    Choose one of the two ways

    1. With JATOS' UI (easiest and recommended): Put the Prolific link in the End Redirect URL field of your Study Properties

      screenshot

    2. With jatos.js: Include jatos.endStudyAndRedirect in the JavaScript of your last component

      E.g. but change this URL to the one you see in Prolific

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

      You can combine it with sending result data

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    - +
    Skip to main content
    Version: 3.7.x

    Use Prolific

    It is very easy to use JATOS together with Prolific to recruit participants.

    This is what the New Study page in Prolific looks like:

    Prolific screenshot

    In the field under What is the URL of your study? (first red box in the screenshot), 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).

    2. (Optional) 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. Click on 'Show advanced' and then 'Add parameters' like in the screenshot.

    Prolific screenshot

    Then you can access those URL parameters in your study's JavaScript via jatos.urlQueryParameters.

    3. Redirect to Prolific's end page after the study is done​

    The second red box contains a link that will (re)direct the participant to a Prolific page, with information on how to claim their payment.

    Choose one of the two ways

    1. With JATOS' UI (easiest and recommended): Put the Prolific link in the End Redirect URL field of your Study Properties

      screenshot

    2. With jatos.js: Include jatos.endStudyAndRedirect in the JavaScript of your last component

      E.g. but change this URL to the one you see in Prolific

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

      You can combine it with sending result data

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    + \ No newline at end of file diff --git a/3.7.x/User-Manager.html b/3.7.x/User-Manager.html index 7d64418e0..3d8377c4d 100644 --- a/3.7.x/User-Manager.html +++ b/3.7.x/User-Manager.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Manage JATOS users

    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 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

    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

    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​

    Superusers exist in JATOS only since version 3.7.4. By default the ability to turn a user into a Superuser is deactivated and has to be activated in the production.conf 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.

    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 production.conf, 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.

    - +
    Skip to main content
    Version: 3.7.x

    Manage JATOS users

    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 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

    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

    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​

    Superusers exist in JATOS only since version 3.7.4. By default the ability to turn a user into a Superuser is deactivated and has to be activated in the production.conf 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.

    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 production.conf, 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.

    + \ No newline at end of file diff --git a/3.7.x/Whats-JATOS.html b/3.7.x/Whats-JATOS.html index 7a279ed9c..b6ee931f5 100644 --- a/3.7.x/Whats-JATOS.html +++ b/3.7.x/Whats-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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 workers, to e.g. make sure that each participant does your study only once.
    • Export/Import studies to facilitate exchange with other researchers.
    • You can try out JATOS on cortex, our test server.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 100 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    - +
    Skip to main content
    Version: 3.7.x

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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 workers, to e.g. make sure that each participant does your study only once.
    • Export/Import studies to facilitate exchange with other researchers.
    • You can try out JATOS on cortex, our test server.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 100 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    + \ No newline at end of file diff --git a/3.7.x/Worker-Types.html b/3.7.x/Worker-Types.html index 4d8c7d788..ffab4ed17 100644 --- a/3.7.x/Worker-Types.html +++ b/3.7.x/Worker-Types.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Worker Types

    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.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Icon
    Typical useDuring study developmentSmall targeted group, each one of them gets a linkSmall targeted group of workers who pilot the study or need to do it multiple timesBigger groups but with less control; link shared e.g. via social mediaBigger groups and where the workers need to do it multiple timesFor Amazon Mechanical Turk
    Created when?Together with the JATOS userWhen you create the linkWhen you create the linkOn-the-fly whenever someone uses the linkOn-the-fly whenever someone uses the linkOn-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
    Possible bulk creation
    Run 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). 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

    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

    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). 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

    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 page for more details on this.

    - +
    Skip to main content
    Version: 3.7.x

    Worker Types

    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.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Icon
    Typical useDuring study developmentSmall targeted group, each one of them gets a linkSmall targeted group of workers who pilot the study or need to do it multiple timesBigger groups but with less control; link shared e.g. via social mediaBigger groups and where the workers need to do it multiple timesFor Amazon Mechanical Turk
    Created when?Together with the JATOS userWhen you create the linkWhen you create the linkOn-the-fly whenever someone uses the linkOn-the-fly whenever someone uses the linkOn-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
    Possible bulk creation
    Run 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). 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

    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

    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). 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

    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 page for more details on this.

    + \ No newline at end of file diff --git a/3.7.x/Write-Group-Studies-I-Setup.html b/3.7.x/Write-Group-Studies-I-Setup.html index 3f42167d0..f0c20bd40 100644 --- a/3.7.x/Write-Group-Studies-I-Setup.html +++ b/3.7.x/Write-Group-Studies-I-Setup.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study checkbox in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 (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

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 (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 (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    - +
    Skip to main content
    Version: 3.7.x

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study checkbox in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 (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

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 (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 (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    + \ No newline at end of file diff --git a/3.7.x/Write-Group-Studies-II-JavaScript-and-Messaging.html b/3.7.x/Write-Group-Studies-II-JavaScript-and-Messaging.html index 9da08f660..f23fae917 100644 --- a/3.7.x/Write-Group-Studies-II-JavaScript-and-Messaging.html +++ b/3.7.x/Write-Group-Studies-II-JavaScript-and-Messaging.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.7.x

    Write Group Studies II - JavaScript and Messaging

    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:

    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 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.

    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.

    Reassigning to a different group​

    To move a worker from one group to a different one, use jatos.reassignGroup. 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 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. Alternatively you can fix a group in JATOS' GUI, in the -Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    - +Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    + \ No newline at end of file diff --git a/3.7.x/Write-your-own-Study-Basics-and-Beyond.html b/3.7.x/Write-your-own-Study-Basics-and-Beyond.html index 16295813a..d0f4cd993 100644 --- a/3.7.x/Write-your-own-Study-Basics-and-Beyond.html +++ b/3.7.x/Write-your-own-Study-Basics-and-Beyond.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.7.x

    Write your own Study - Basics and Beyond

    After you created a new study ... what comes next?

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    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 and click on Components -> New.

    New Component

    Then in the following form you define the component's properties: enter 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

    Click on 'Create' and you are done. If you add more than one component you can change the order in which they run by drag-and-drop on the position button.

    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>
        <head>
          <script src="jatos.js"></script>
        </head>
      </html>

    2. 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 untill jatos.js is finished initializing.

      <script>
        jatos.onLoad(function() {
          // Start here with your code that uses jatos.js' variables and functions
        });
      </script>

    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.

    jatos.js Reference​

    In your JavaScript you will use jatos.js to handle everything JATOS related and in its reference every function and field is described in detail.

    Study JSON Input and Component JSON 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 JSON Input or Component JSON Input because both can be easily edited in the Study Properties or Component Properties.

    Study Properties / JSON input

    Both input fields take JSON 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 JSON Input and Component JSON 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 JSON Input

    {
       "introduction": "this is a text",
       "order": [3, 1, 2]
    }

    you can access those fields in your JavaScript with jatos.studyJsonInput.introduction 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.

    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, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    - +To get an idea it's best to start with examples, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    + \ No newline at end of file diff --git a/3.7.x/jatos.js-Reference.html b/3.7.x/jatos.js-Reference.html index d1041feb2..7c4a507c5 100644 --- a/3.7.x/jatos.js-Reference.html +++ b/3.7.x/jatos.js-Reference.html @@ -10,7 +10,7 @@ - + @@ -18,8 +18,8 @@
    Skip to main content
    Version: 3.7.x

    jatos.js Reference

    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 <head> section with the following line:

    <script src="jatos.js"></script>

    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.

    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

    jatos.groupResultId​

    see 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 link to start a Personal Single Run:

      http://localhost:9000/publix/50/start?batchId=47&personalSingleWorkerId=506

      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/50/start?batchId=47&personalSingleWorkerId=506&foo=bar&a=123

      Then those parameter will be accessible during the study run as jatos.urlQueryParameters.a and jatos.urlQueryParameters.foo.

    2. 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).

    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

    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

    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

    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

    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

    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

    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

    jatos.httpTimeout = 30000; // Sets HTTP timeout to 30 seconds

    jatos.httpRetry​

    Some jatos functions (e.g. jatos.sendResultData) send an Ajax 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

    jatos.httpRetry = 2; // Attempts 2 retries of failed Ajax requests

    jatos.httpRetryWait​

    Same as jatos.httpRetry but this variable defines the waiting time between the retries. The default is 1000 ms.

    Example

    jatos.httpRetryWait = 5000; // Sets Ajax 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

    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

    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

      jatos.addAbortButton()

    2. Adds a cancel button and changes some properties

      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"
      });

    3. Adds a cancel button and changes the position to the bottom-left

      jatos.addAbortButton({
        style: "left:1em"
      });

    4. Adds a cancel button and calls 'myFunction' if pressed

      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:

    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.

      jatos.showOverlay()

    2. Shows text only

      jatos.showOverlay({
        text: "Please have a coffee break for 5 minutes",
        showImg: false
      });

    3. Shows text only

      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

    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:

    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

    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. This is useful in debugging.

    Example

    jatos.catchAndLogErrors();

    jatos.addJatosIds​

    Convenience function that adds some 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

    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

    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 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, 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

    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

    2. 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

      jatos.startComponent(23);

    2. Jump to component by using its UUID

      jatos.startComponent("3d277289-754b-4fd6-aa76-c8404deda02e");

    3. Send result data and jump to another component

      var resultData = "my important result data";
      jatos.startComponent(23, resultData);

    4. Send result data, jump to another component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startComponentByPos(3);

    2. Send result data and jump to component with position 3

      var resultData = "my important result data";
      jatos.startComponentByPos(3, resultData);

    3. Send result data, jump to component in position 3 and send a message back that will be visible in JATOS result pages and log

      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

    2. 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"

      jatos.startComponentByTitle("Some title");

    2. Send result data and jump to component with title "Some title"

      var resultData = "my important result data";
      jatos.startComponentByTitle("Some title", resultData);

    3. 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 

      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

    2. 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

      jatos.startNextComponent();

    2. Send result data and jump to the next component

      var resultData = "my important result data";
      jatos.startNextComponent(resultData);

    3. Send result data, jump to the next component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startLastComponent();

    2. Send result data and jump to the last component

      var resultData = "my important result data";
      jatos.startLastComponent(resultData);

    3. Send result data, jump to the last component and send a message back that will be visible in JATOS result pages and log

      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

      jatos.abortStudy();

    2. Additionally send a message

      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, 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

      jatos.abortStudyAjax();

    2. Abort study with a message that will be sent back to JATOS and shown in the result page and put in the log

      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

    2. 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

      jatos.endStudy();

    2. End study and send a message back that will be visible in JATOS result pages and log

      jatos.endStudy(true, "everything worked fine");

    3. Indicate a failure - leads to study result state FAIL

      jatos.endStudy(false, "internal JS error");

    4. Send result data and end study

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudy(resultData);

    5. Send result data, end study and send a message back that will be visible in JATOS result pages and log

      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, 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

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    2. End study and redirect afterwards. Send result data.

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);

    3. End study and redirect afterwards. A message will be sent back to JATOS and shown in the result page and put in the log.

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", true, "everything worked fine");

    4. End study and indicate a failure and send a message. Does not redirect.

      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, 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

      jatos.endStudyAjax();

    2. End study with a message that will be sent back to JATOS and shown in the result page and put in the log

      jatos.endStudyAjax(true, "everything worked fine");

    3. Indicate a failure and send a message

      jatos.endStudyAjax(false, "some error description");

    4. End study and show the confirmation code to the MTurk worker

      jatos.endStudyAjax().then((confirmationCode) => {
        // Show the confirmation code to the worker
      });

    5. Use Promise to submit result data and afterwards, end the study and move to another URL (see also)

      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"));

    6. Send result data and end study

      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, 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

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData);

    2. 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

      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)

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData, () => { jatos.startComponentByPos(4) });

    2. Or by using the returned Promise

      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, 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

      var resultData = { "a": 123, "b": 789, "c": 100 };
      jatos.appendResultData(resultData);

    2. Use mulitple jatos.appendResultData in a row

      jatos.appendResultData({"a": 1})
         .then(() => jatos.appendResultData({"b": 2}))
         .then(() => jatos.appendResultData({"c": 3}))
         .catch(() => console.log('Something went wrong'));

    3. You can use it together with jatos.startNextComponent to first append result data and afterwards jump to the next component

      var resultData = { "a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData, jatos.startNextComponent);

    4. Or by using the returned Promise

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData)
         .then(() => jatos.startNextComponent())
         .catch(() => console.log('Something went wrong'));

    5. Or together with jatos.startComponentByPos to start a particular component (here at position 4)

      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, to signal success or failure in the transfer.

    • @param {Blob, string or object} obj - Data to be uploaded as a file. Can be 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

      jatos.uploadResultFile("this is my data", "example.txt")
         .then(() => console.log("File was successfully uploaded"))
         .catch(() => console.log("File upload failed"));

    2. Upload object as JSON

      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"));

    3. Upload text as Blob

      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"));

    4. Turn canvas into Blob and upload as image file. It assumes you have an canvas element with ID 'canvas'.

      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"));
      });

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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 are returned as a Blob. It offers callbacks, either as parameter or via a 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

      jatos.downloadResultFile("example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    2. Download JSON file

      jatos.downloadResultFile("example.json")
         .then((obj) => console.log(JSON.stringify(obj)))
         .catch(() => console.log("File download failed"));

    3. Download image and display it in a canvas element

      jatos.downloadResultFile("canvas.png")
         .then((blob) => { document.getElementById("canvas").src = URL.createObjectURL(blob) })
         .catch(() => console.log("File download failed"));

    4. Download file and specify that the file was uploaded in the first component

      jatos.downloadResultFile(1, "example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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). 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.

    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) and JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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

      jatos.onBatchSession(function(path, op){
        console.log("Batch Session was updated in path " + path + " with operation " + op);
      });

    2. onBatchSession is often used together with jatos.batchSession.find to get the updated value:

      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"}

      // 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

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.batchSession.set("b", "koala")
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    3. Have a series of Batch Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

      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

    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).

    • @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"}}

      jatos.batchSession.test("/a", 123); // returns true
      jatos.batchSession.test("/a", 10); // returns false
      jatos.batchSession.test("/b/b1", "flowers"); // returns true

    2. 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.

      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). 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

      jatos.batchSession.add("/a", 100);

      After the Batch Session is successfully updated the new object is {"a": 100}.

    2. Add to Batch Session

      If the Batch Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or fail

      jatos.batchSession.add("/b", 123)
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    4. Add an object:

      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.

    5. Add an array:

      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]}.

    6. Add an element to an array:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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]}.

    7. Append to the end of an array using /-:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    8. Have a series of Batch Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    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, 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

      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));
      }

    2. Example that defines the onOpen, onMemberOpen, and onMessage callbacks

      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. 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

    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

      var msg = "Message for group member 1063";
      jatos.sendGroupMsgTo("1063", msg)

    2. Use the onMemberOpen callback to send a message right after a new member opened their group channel

      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, 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

    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, 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

    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, 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

    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

    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

    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

    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

    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

    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) and broadcast messaging (jatos.sendGroupMsg) (or: more general information about the different session types).

    In difference to 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). 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.

    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) and -JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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"}

      // 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.

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

    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

    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).

    • @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"}}

      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.

      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). 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

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    - +JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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.

    Examples

    1. Get a field from the Group Session

      Given the Group Session is {"a": 1000, "b": "watermelon"}

      // 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.

    2. 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"}}

      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.

    Examples

    1. Set a field in the Group Session

      If the Group Session is {"a": 1234}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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.

    Example

    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'.

    Examples

    1. Set the whole Group Session at once

      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.

    2. Use returned Promise to handle success or failure

      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 {}.

    Examples

    1. Clear the whole Group Session

      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.

    2. Use returned Promise to handle success or failure

      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.

    Example

    Given the Group Session is {"a": {"a1": "foo", "a2": "bar"}, "b": 999}

    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).

    Example

    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).

    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"}}

      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.

      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). 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.

    Examples

    1. Add an a field to the empty Group Session

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    Examples

    1. Remove a field from the Group Session

      If the Group Session is {"a": 100, "b": 123} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Replace a field in the Group Session

      If the Group Session is {"a": 100, "b": 123} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Copy a field in the Group Session from one location to another

      If the Group Session is {"a": "jatos"} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Move a field in the Group Session from one location to another

      If the Group Session is {"a": "jatos"} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    + \ No newline at end of file diff --git a/3.7.x/jsPsych-and-JATOS.html b/3.7.x/jsPsych-and-JATOS.html index 0270a3cf3..74eba63a9 100644 --- a/3.7.x/jsPsych-and-JATOS.html +++ b/3.7.x/jsPsych-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. Tell jsPsych to send your result data to JATOS

      var jsPsych = initJsPsych({
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad and if you want add a 'Cancel' button with jatos.addAbortButton.

      jatos.onLoad(() => {
        jatos.addAbortButton();
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    - +
    Skip to main content
    Version: 3.7.x

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. Tell jsPsych to send your result data to JATOS

      var jsPsych = initJsPsych({
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad and if you want add a 'Cancel' button with jatos.addAbortButton.

      jatos.onLoad(() => {
        jatos.addAbortButton();
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    + \ No newline at end of file diff --git a/3.7.x/labjs-and-JATOS.html b/3.7.x/labjs-and-JATOS.html index 2f18a7c44..8c0b96087 100644 --- a/3.7.x/labjs-and-JATOS.html +++ b/3.7.x/labjs-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.7.x

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their Builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    - +
    Skip to main content
    Version: 3.7.x

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their Builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    + \ No newline at end of file diff --git a/3.8.x/Adapt-pre-written-code-to-run-it-in-JATOS.html b/3.8.x/Adapt-pre-written-code-to-run-it-in-JATOS.html index 2a40780c3..1c6266091 100644 --- a/3.8.x/Adapt-pre-written-code-to-run-it-in-JATOS.html +++ b/3.8.x/Adapt-pre-written-code-to-run-it-in-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Adapt pre written code to run it in JATOS

    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.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Create the study in your local JATOS​

    1. Create a new study with the 'New Study' button in JATOS' header. Choose a study title and a folder name. Leave the other fields empty for now and click 'Create'. JATOS will have created a new folder within your assets root folder (default is /path_to_your_JATOS/study_assets_root/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. Back in the JATOS GUI, and within the newly created study, create a new component by clicking 'Components' and then 'New'. Choose a component title and set the HTML file name, to the name of the HTML file you just copied into the study folder.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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's and component's 'JSON input data'. 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.
    - +
    Skip to main content
    Version: 3.8.x

    Adapt pre written code to run it in JATOS

    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.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Create the study in your local JATOS​

    1. Create a new study with the 'New Study' button in JATOS' header. Choose a study title and a folder name. Leave the other fields empty for now and click 'Create'. JATOS will have created a new folder within your assets root folder (default is /path_to_your_JATOS/study_assets_root/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. Back in the JATOS GUI, and within the newly created study, create a new component by clicking 'Components' and then 'New'. Choose a component title and set the HTML file name, to the name of the HTML file you just copied into the study folder.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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's and component's 'JSON input data'. 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.
    + \ No newline at end of file diff --git a/3.8.x/Administration.html b/3.8.x/Administration.html index 352297ea9..c98b6b179 100644 --- a/3.8.x/Administration.html +++ b/3.8.x/Administration.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    On the menu you will find links to two additional administration pages:

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    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.

    For larger JATOS installation it can take up to a couple minutes to gather all data for this page

    Studies Administration

    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.
    - +
    Skip to main content
    Version: 3.8.x

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    On the menu you will find links to two additional administration pages:

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    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.

    For larger JATOS installation it can take up to a couple minutes to gather all data for this page

    Studies Administration

    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.
    + \ No newline at end of file diff --git a/3.8.x/Bring-your-JATOS-online.html b/3.8.x/Bring-your-JATOS-online.html index d47c0308a..6a7876ccd 100644 --- a/3.8.x/Bring-your-JATOS-online.html +++ b/3.8.x/Bring-your-JATOS-online.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Bring your JATOS online

    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 timeSetup difficultyCostNumber of JATOS user / JATOS workers
    1. Expose your local JATOSfasteasynoneyou / few †
    2. Cloud serverfast to mediumdepends on your vendoryesmany / many ‡
    3. Own servermedium to slow (depends on your IT)needs admin skillsask your ITmany / many ‡

    †) 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

    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 or JATOS on AWS (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

    - +‡) 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

    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 or JATOS on AWS (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

    + \ No newline at end of file diff --git a/3.8.x/Change-studys-members.html b/3.8.x/Change-studys-members.html index 9ffbdf46e..52f095da9 100644 --- a/3.8.x/Change-studys-members.html +++ b/3.8.x/Change-studys-members.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Change study's members

    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&#39;s members button

    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&#39;s members

    - +
    Skip to main content
    Version: 3.8.x

    Change study's members

    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&#39;s members button

    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&#39;s members

    + \ No newline at end of file diff --git a/3.8.x/Combine-two-pre-written-studies-into-one.html b/3.8.x/Combine-two-pre-written-studies-into-one.html index e6d6d5dba..aeaa85ffd 100644 --- a/3.8.x/Combine-two-pre-written-studies-into-one.html +++ b/3.8.x/Combine-two-pre-written-studies-into-one.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Combine two pre-written studies into one

    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 and a perceptual experiment with OSWeb. 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 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.
    2. Information about where your study assets are: Go to 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.
    3. The .jzip for the first half of your study.
    4. 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. A JZIP study archive file is a ZIP archive with a standarized 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:

    jatos.startNextComponent(myResultDataObject);

    and not 

    jatos.endStudy(myResultDataObject);
    - +
    Skip to main content
    Version: 3.8.x

    Combine two pre-written studies into one

    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 and a perceptual experiment with OSWeb. 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 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.
    2. Information about where your study assets are: Go to 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.
    3. The .jzip for the first half of your study.
    4. 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. A JZIP study archive file is a ZIP archive with a standarized 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:

    jatos.startNextComponent(myResultDataObject);

    and not 

    jatos.endStudy(myResultDataObject);
    + \ No newline at end of file diff --git a/3.8.x/Connect-to-Mechanical-Turk.html b/3.8.x/Connect-to-Mechanical-Turk.html index 29117c121..dc1606a59 100644 --- a/3.8.x/Connect-to-Mechanical-Turk.html +++ b/3.8.x/Connect-to-Mechanical-Turk.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    - +
    Skip to main content
    Version: 3.8.x

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    + \ No newline at end of file diff --git a/3.8.x/Contact-us.html b/3.8.x/Contact-us.html index 827c8a44a..9fe8da8ee 100644 --- a/3.8.x/Contact-us.html +++ b/3.8.x/Contact-us.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    - +
    Skip to main content
    Version: 3.8.x

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    + \ No newline at end of file diff --git a/3.8.x/Create-a-new-study.html b/3.8.x/Create-a-new-study.html index ff6d0f663..e08e9e9ee 100644 --- a/3.8.x/Create-a-new-study.html +++ b/3.8.x/Create-a-new-study.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Create a new study

    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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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.

    Press the New Study button in the header of your local JATOS. Then edit the study properties and add new components manually. All source code for your study has to got into the study assets folder you defined in the the study properties. 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) as a prototype and modify it bit by bit. Press on the Import button in the header and select the file of the study. Then see the source code in your study assets folder, which is usually in your JATOS installation folder.

    - +
    Skip to main content
    Version: 3.8.x

    Create a new study

    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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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.

    Press the New Study button in the header of your local JATOS. Then edit the study properties and add new components manually. All source code for your study has to got into the study assets folder you defined in the the study properties. 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) as a prototype and modify it bit by bit. Press on the Import button in the header and select the file of the study. Then see the source code in your study assets folder, which is usually in your JATOS installation folder.

    + \ No newline at end of file diff --git a/3.8.x/Cross-sectional-and-longitudinal-studies.html b/3.8.x/Cross-sectional-and-longitudinal-studies.html index 6824a6b00..3bf251714 100644 --- a/3.8.x/Cross-sectional-and-longitudinal-studies.html +++ b/3.8.x/Cross-sectional-and-longitudinal-studies.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    - +
    Skip to main content
    Version: 3.8.x

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    + \ No newline at end of file diff --git a/3.8.x/Customize-JATOS-Home-Page.html b/3.8.x/Customize-JATOS-Home-Page.html index dd9f97e66..6d883d44e 100644 --- a/3.8.x/Customize-JATOS-Home-Page.html +++ b/3.8.x/Customize-JATOS-Home-Page.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Customize JATOS' Home Page

    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.

    template customized home page

    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.

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    - +
    Skip to main content
    Version: 3.8.x

    Customize JATOS' Home Page

    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.

    template customized home page

    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.

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    + \ No newline at end of file diff --git a/3.8.x/Data-Privacy-and-Ethics.html b/3.8.x/Data-Privacy-and-Ethics.html index 3b9e19baa..6968fe02f 100644 --- a/3.8.x/Data-Privacy-and-Ethics.html +++ b/3.8.x/Data-Privacy-and-Ethics.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Data Privacy and Ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    - +
    Skip to main content
    Version: 3.8.x

    Data Privacy and Ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    + \ No newline at end of file diff --git a/3.8.x/Deploy-to-a-server-installation.html b/3.8.x/Deploy-to-a-server-installation.html index 265c5678c..3694e5bf7 100644 --- a/3.8.x/Deploy-to-a-server-installation.html +++ b/3.8.x/Deploy-to-a-server-installation.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Deploy to a server installation

    Usually you conveniently develop your study on your local computer where you have a local installation of JATOS. Then just use the export and import buttons in your installations to transfer the study to your JATOS server.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Here's a little sketch of the same three steps above -jzip workflow

    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 black bar on top. A server installation has a light-grey bar.
    • A .jzip file is a JATOS Study Archive. 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 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.
    - +jzip workflow

    Please note that:

    + \ No newline at end of file diff --git a/3.8.x/End-page-after-your-study-finished.html b/3.8.x/End-page-after-your-study-finished.html index cf0c27cde..f65a8a9a1 100644 --- a/3.8.x/End-page-after-your-study-finished.html +++ b/3.8.x/End-page-after-your-study-finished.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    End page - After your study finished

    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 finshed. 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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    - +
    Skip to main content
    Version: 3.8.x

    End page - After your study finished

    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 finshed. 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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    + \ No newline at end of file diff --git a/3.8.x/Example-Group-Studies.html b/3.8.x/Example-Group-Studies.html index a8cee5010..6c266c67c 100644 --- a/3.8.x/Example-Group-Studies.html +++ b/3.8.x/Example-Group-Studies.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    - +
    Skip to main content
    Version: 3.8.x

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    + \ No newline at end of file diff --git a/3.8.x/Expose-your-local-JATOS.html b/3.8.x/Expose-your-local-JATOS.html index ace0a89c1..f3f8adcdd 100644 --- a/3.8.x/Expose-your-local-JATOS.html +++ b/3.8.x/Expose-your-local-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create study links 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.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create study links 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/.

    - +
    Skip to main content
    Version: 3.8.x

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create study links 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.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create study links 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/.

    + \ No newline at end of file diff --git a/3.8.x/Get-started.html b/3.8.x/Get-started.html index c8572bf8e..8651b7176 100644 --- a/3.8.x/Get-started.html +++ b/3.8.x/Get-started.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.8.x

    Get started

    Get started in 4 steps​

    1. Download JATOS and install a local instance

    2. Open JATOS' GUI by going to localhost:9000 in your browser window

    3. Download and import an example study

      1. Download one of the Example Studies, e.g. the 'Go- / No-Go Task' with jsPsych. Do not unzip the downloaded file.

      2. Import the study into JATOS: Go to JATOS' GUI in your browser and click on Import Study in the header. Choose the .jzip file you just downloaded. The imported study should appear in the sidebar on the left.

    4. 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).

      Here's a screenshot of a study's results view: Results View screenshot

    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/.

    Here's a screenshot of a component's properties view: -GUI screenshot

    - +GUI screenshot

    + \ No newline at end of file diff --git a/3.8.x/Install-JATOS-via-Docker.html b/3.8.x/Install-JATOS-via-Docker.html index 89535cb44..a2535eabb 100644 --- a/3.8.x/Install-JATOS-via-Docker.html +++ b/3.8.x/Install-JATOS-via-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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 for some advanced Docker setup.

    Installation with Docker​

    1. In your terminal:

      • Get the latest release:
      docker pull jatos/jatos:latest
      • or a specific release (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    2. Run JATOS (change latest to your version)

      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.

    3. 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 - it should show the JATOS login screen
      • Check JATOS' administration page: 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

    4. Always change the admin's password after first installation: Go to 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:

    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:

    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 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):

    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 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):

    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 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:

    docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest

    Persist data with volumes​

    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:

    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:

    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, you can simply use the auto-update feature to update JATOS to newer versions.

    2. 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 - If you don't use volumes your data stored in JATOS will be lost.

    - +
    Skip to main content
    Version: 3.8.x

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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 for some advanced Docker setup.

    Installation with Docker​

    1. In your terminal:

      • Get the latest release:
      docker pull jatos/jatos:latest
      • or a specific release (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    2. Run JATOS (change latest to your version)

      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.

    3. 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 - it should show the JATOS login screen
      • Check JATOS' administration page: 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

    4. Always change the admin's password after first installation: Go to 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:

    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:

    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 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):

    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 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):

    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 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:

    docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest

    Persist data with volumes​

    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:

    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:

    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, you can simply use the auto-update feature to update JATOS to newer versions.

    2. 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 - If you don't use volumes your data stored in JATOS will be lost.

    + \ No newline at end of file diff --git a/3.8.x/Installation.html b/3.8.x/Installation.html index 1b5a5bc8c..ebe76d4c1 100644 --- a/3.8.x/Installation.html +++ b/3.8.x/Installation.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Installation

    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 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) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
      • Without Java: jatos.zip
      • Bundled with Java: jatos_win_java.zip
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
      • Without Java: jatos.zip
      • For MacOS bundled with Java: jatos_mac_java.zip
      • For Linux bundled with Java: jatos_linux_java.zip
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. (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.)
    6. All set! Now go to the browser of your choice and open 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 and play around with it.

    - +If you don't have Java installed, you can either download and install it (e.g. from adoptium.net) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. (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.)
    6. All set! Now go to the browser of your choice and open 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 and play around with it.

    + \ No newline at end of file diff --git a/3.8.x/JATOS-API.html b/3.8.x/JATOS-API.html index ed4f8cffc..d333daf41 100644 --- a/3.8.x/JATOS-API.html +++ b/3.8.x/JATOS-API.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS API

    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 in your local JATOS. (The JATOS API uses personal access tokens with bearer authentication.)
    2. Copy your token
    3. Go to petstore.swagger.io. You'll see all API endpoints and their descriptions.
    4. 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.
    5. Choose the server http://localhost:9000 (probably already set)
    6. 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. You can use petstore.swagger.io 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.

    Authentication​

    The JATOS API uses bearer authentication. It's pretty simple.

    From swagger.io:

    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 <token> with your token):

    Authorization: Bearer <token>

    And an example in different tools/languages with the endpoint /jatos/api/v1/admin/token that just returns some info about the used token:

    curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token

    Personal access tokens​

    The JATOS API uses personal access tokens (PATs or API tokens).

    From wikipedia:

    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 your user's page (click on your name in the top-right header). Then click the button API Tokens.

    API token 1

    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

    Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

    API token 1

    In the token overview windows you can temporarily deactivate a token or delete it altogether.

    API token 1

    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:

    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'

    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
    - +
    Skip to main content
    Version: 3.8.x

    JATOS API

    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 in your local JATOS. (The JATOS API uses personal access tokens with bearer authentication.)
    2. Copy your token
    3. Go to petstore.swagger.io. You'll see all API endpoints and their descriptions.
    4. 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.
    5. Choose the server http://localhost:9000 (probably already set)
    6. 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. You can use petstore.swagger.io 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.

    Authentication​

    The JATOS API uses bearer authentication. It's pretty simple.

    From swagger.io:

    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 <token> with your token):

    Authorization: Bearer <token>

    And an example in different tools/languages with the endpoint /jatos/api/v1/admin/token that just returns some info about the used token:

    curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token

    Personal access tokens​

    The JATOS API uses personal access tokens (PATs or API tokens).

    From wikipedia:

    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 your user's page (click on your name in the top-right header). Then click the button API Tokens.

    API token 1

    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

    Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

    API token 1

    In the token overview windows you can temporarily deactivate a token or delete it altogether.

    API token 1

    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:

    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'

    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
    + \ No newline at end of file diff --git a/3.8.x/JATOS-Results-Archive-JRZIP.html b/3.8.x/JATOS-Results-Archive-JRZIP.html index 04c11eab4..a00543335 100644 --- a/3.8.x/JATOS-Results-Archive-JRZIP.html +++ b/3.8.x/JATOS-Results-Archive-JRZIP.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS Results Archive (JRZIP)

    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​

    {
        "$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"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    - +
    Skip to main content
    Version: 3.8.x

    JATOS Results Archive (JRZIP)

    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​

    {
        "$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"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    + \ No newline at end of file diff --git a/3.8.x/JATOS-Study-Archive-JZIP.html b/3.8.x/JATOS-Study-Archive-JZIP.html index fd7307c56..7a474d12a 100644 --- a/3.8.x/JATOS-Study-Archive-JZIP.html +++ b/3.8.x/JATOS-Study-Archive-JZIP.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS Study Archive (JZIP)

    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​

    {
        "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​

    {
        "$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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    - +
    Skip to main content
    Version: 3.8.x

    JATOS Study Archive (JZIP)

    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​

    {
        "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​

    {
        "$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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    + \ No newline at end of file diff --git a/3.8.x/JATOS-Tryout-Server.html b/3.8.x/JATOS-Tryout-Server.html index 15a659168..5db484ff1 100644 --- a/3.8.x/JATOS-Tryout-Server.html +++ b/3.8.x/JATOS-Tryout-Server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    - +
    Skip to main content
    Version: 3.8.x

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    + \ No newline at end of file diff --git a/3.8.x/JATOS-in-Amazons-Cloud-without-Docker.html b/3.8.x/JATOS-in-Amazons-Cloud-without-Docker.html index f2835e559..37f162625 100644 --- a/3.8.x/JATOS-in-Amazons-Cloud-without-Docker.html +++ b/3.8.x/JATOS-in-Amazons-Cloud-without-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache 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
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    - +
    Skip to main content
    Version: 3.8.x

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache 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
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    + \ No newline at end of file diff --git a/3.8.x/JATOS-in-a-cluster.html b/3.8.x/JATOS-in-a-cluster.html index 2b49435a7..c7353186a 100644 --- a/3.8.x/JATOS-in-a-cluster.html +++ b/3.8.x/JATOS-in-a-cluster.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS in a cluster

    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 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. 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 additionally (if you haven't already):

    1. Set -Djatos.multiNode=true in the command section of the jatos service.
    2. 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:

    docker compose -f compose.yaml up --scale jatos=2

    JATOS with Kubernetes​

    Kubernetes 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 - but with some adjustments it should work on any Kubernetes cluster.

    For the JATOS cluster we use Kustomize to define Kubernetes objects through kustomization YAML files.

    We assembled all necessary files in a git repository.

    git clone https://github.com/JATOS/JATOS_with_kubernetes.git

    The file kustomization.yaml defines our secrets and specifies the resource file, jatos.yaml, that describes the JATOS cluster.

    Then, after you set up everything, you can start the cluster with:

    kubectl apply -k <my_JATOS_kustomize_directory>

    Load-balancing and scaling​

    In our jatos.yaml, for auto-balancing in our JATOS cluster, we use the one integrated in DigitalOcean. This is specified in the Service object, with the annotation kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer".

    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%. 

    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, 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 for this purpose: nfs-server-provisioner. And since we want to run on DigitalOcean we need the parameter persistence.storageClass set to do-block-storage.

    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 the NFS storage is used in a PersistentVolumeClaim:

    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:

    volumes:
      - name: jatos-data-storage
        persistentVolumeClaim:
          claimName: jatos-data-pv-claim

    Configure JATOS' deployment​

    In 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.

    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 file and then just referenced in 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 to get started.

    In 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, a startupProbe that accounts for this. You might have to tweak failureThreshold and periodSeconds on your system.

    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 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. 

    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.

    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 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.
    2. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation.
    3. And please do backups before updating.
    - +
    Skip to main content
    Version: 3.8.x

    JATOS in a cluster

    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 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. 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 additionally (if you haven't already):

    1. Set -Djatos.multiNode=true in the command section of the jatos service.
    2. 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:

    docker compose -f compose.yaml up --scale jatos=2

    JATOS with Kubernetes​

    Kubernetes 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 - but with some adjustments it should work on any Kubernetes cluster.

    For the JATOS cluster we use Kustomize to define Kubernetes objects through kustomization YAML files.

    We assembled all necessary files in a git repository.

    git clone https://github.com/JATOS/JATOS_with_kubernetes.git

    The file kustomization.yaml defines our secrets and specifies the resource file, jatos.yaml, that describes the JATOS cluster.

    Then, after you set up everything, you can start the cluster with:

    kubectl apply -k <my_JATOS_kustomize_directory>

    Load-balancing and scaling​

    In our jatos.yaml, for auto-balancing in our JATOS cluster, we use the one integrated in DigitalOcean. This is specified in the Service object, with the annotation kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer".

    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%. 

    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, 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 for this purpose: nfs-server-provisioner. And since we want to run on DigitalOcean we need the parameter persistence.storageClass set to do-block-storage.

    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 the NFS storage is used in a PersistentVolumeClaim:

    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:

    volumes:
      - name: jatos-data-storage
        persistentVolumeClaim:
          claimName: jatos-data-pv-claim

    Configure JATOS' deployment​

    In 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.

    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 file and then just referenced in 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 to get started.

    In 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, a startupProbe that accounts for this. You might have to tweak failureThreshold and periodSeconds on your system.

    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 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. 

    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.

    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 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.
    2. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation.
    3. And please do backups before updating.
    + \ No newline at end of file diff --git a/3.8.x/JATOS-on-DigitalOcean.html b/3.8.x/JATOS-on-DigitalOcean.html index d4162712d..951475445 100644 --- a/3.8.x/JATOS-on-DigitalOcean.html +++ b/3.8.x/JATOS-on-DigitalOcean.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS on DigitalOcean

    Here we explain how to install JATOS in the cloud by using DigitalOcean. 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.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Create a Droplet (this is what DigitalOcean calls a virtual machine that we want to use as a server).

    3. Choose the Region that is nearest to your users.

    4. Choose an image from Marketplace: select one with Docker on Ubuntu pre-installed.

    5. 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.

    6. Choose an authentication method

    7. Click on Advanced Options and activate Add Initialization scripts. Then copy+paste the following script in the text field:

      #!/bin/bash
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      You can change 'latest' to the specific version you need.

    8. Finally click the Create Droplet button

    9. 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.

    10. 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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source 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
    2. Set up your DNS
    3. Restart droplet
    4. 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) but in the field for the Add Initialization scripts put the following script:

    #!/bin/bash

    # Change to your email and domain (for Let's Encrypt)
    email=myemail@example.org
    domain=my.domain.org

    cat >/root/compose.yaml <<EOL
    version: "3.8"

    services:

      traefik:
        image: "traefik:v2.10"
        container_name: "traefik"
        command:
          #- "--log.level=DEBUG"
          - "--api.insecure=true"
          - "--providers.docker=true"
          - "--providers.docker.exposedbydefault=false"
          - "--entrypoints.web.address=:80"
          - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
          - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
          - "--entrypoints.websecure.address=:443"
          - "--certificatesresolvers.jatosresolver.acme.tlschallenge=true"
          #- "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
          - "--certificatesresolvers.jatosresolver.acme.email=${email}"
          - "--certificatesresolvers.jatosresolver.acme.storage=/letsencrypt/acme.json"
        ports:
          - "80:80"
          - "443:443"
        volumes:
          - "./letsencrypt:/letsencrypt"
          - "/var/run/docker.sock:/var/run/docker.sock:ro"

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        ports:
          - "9000:9000"
        volumes:
          - "jatos-logs:/opt/jatos/logs"
          - "jatos-data:/opt/jatos_data"
        labels:
          - "traefik.enable=true"
          - "traefik.http.routers.jatos.rule=Host(\`${domain}\`)"
          - "traefik.http.services.jatos.loadbalancer.server.port=9000"
          - "traefik.http.routers.jatos.entrypoints=websecure"
          - "traefik.http.routers.jatos.tls.certresolver=jatosresolver"

    volumes:
      jatos-data:
      jatos-logs:
    EOL

    docker compose -f /root/compose.yaml up -d

    This script will use Docker Compose to set up Traefik and JATOS. It creates a Docker Compose config file under /root/compose.yaml and then runs it with docker compose up.

    Before you can click the Create Droplet button, change my.domain.org and myemail@example.org (in the top of the script) with your own domain name and email address. Your email is needed to get a certificate from Let's Encrypt for encryption. Also, you might want to set JATOS version to a specific release: change latest in the line image: "jatos/jatos:latest".

    Set up your DNS​

    After you've created your Droplet, you still have to point your domain name to your server's IP address. This is what a DNS (Domain Name Service) does and it involves dealing with things like DNS records, especially A records or AAAA records, and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registrar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Restart​

    Then as a last step, after your domain name points to your server's IP, you have to restart your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and uses HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption and your domain name.

    Misc​

    • Let's Encrypt has a rate limit for the number of certificates. If you are not sure and just want to try it out, uncomment the following line in the Initialization script:

      - "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

      This will let you use their staging server that does not have such rate limit - but you won't get a proper certificate either.

    • The Docker Compose config file that is created during the Droplet initialization has the path /root/compose.yaml and the certificate is stored under /root/letsencrypt/.

    • You can configure JATOS by changing the /root/compose.yaml. You can add all command-line arguments of JATOS in the command section of the jatos service_.

      E.g. to add a welcome message on the home page use -Djatos.brandingUrl:

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.brandingUrl=https://mydomain.com/foobar-university-welcome-page.html'
          ...

      E.g. to let JATOS use an external MySQL database use -Djatos.db.url, -Djatos.db.username, -Djatos.db.password, and -Djatos.db.driver (change IP, port, username and password to the ones of your database)

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.db.url=jdbc:mysql://1.2.3.4: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'
          ...
    - +
    Skip to main content
    Version: 3.8.x

    JATOS on DigitalOcean

    Here we explain how to install JATOS in the cloud by using DigitalOcean. 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.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Create a Droplet (this is what DigitalOcean calls a virtual machine that we want to use as a server).

    3. Choose the Region that is nearest to your users.

    4. Choose an image from Marketplace: select one with Docker on Ubuntu pre-installed.

    5. 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.

    6. Choose an authentication method

    7. Click on Advanced Options and activate Add Initialization scripts. Then copy+paste the following script in the text field:

      #!/bin/bash
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      You can change 'latest' to the specific version you need.

    8. Finally click the Create Droplet button

    9. 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.

    10. 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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source 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
    2. Set up your DNS
    3. Restart droplet
    4. 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) but in the field for the Add Initialization scripts put the following script:

    #!/bin/bash

    # Change to your email and domain (for Let's Encrypt)
    email=myemail@example.org
    domain=my.domain.org

    cat >/root/compose.yaml <<EOL
    version: "3.8"

    services:

      traefik:
        image: "traefik:v2.10"
        container_name: "traefik"
        command:
          #- "--log.level=DEBUG"
          - "--api.insecure=true"
          - "--providers.docker=true"
          - "--providers.docker.exposedbydefault=false"
          - "--entrypoints.web.address=:80"
          - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
          - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
          - "--entrypoints.websecure.address=:443"
          - "--certificatesresolvers.jatosresolver.acme.tlschallenge=true"
          #- "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
          - "--certificatesresolvers.jatosresolver.acme.email=${email}"
          - "--certificatesresolvers.jatosresolver.acme.storage=/letsencrypt/acme.json"
        ports:
          - "80:80"
          - "443:443"
        volumes:
          - "./letsencrypt:/letsencrypt"
          - "/var/run/docker.sock:/var/run/docker.sock:ro"

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        ports:
          - "9000:9000"
        volumes:
          - "jatos-logs:/opt/jatos/logs"
          - "jatos-data:/opt/jatos_data"
        labels:
          - "traefik.enable=true"
          - "traefik.http.routers.jatos.rule=Host(\`${domain}\`)"
          - "traefik.http.services.jatos.loadbalancer.server.port=9000"
          - "traefik.http.routers.jatos.entrypoints=websecure"
          - "traefik.http.routers.jatos.tls.certresolver=jatosresolver"

    volumes:
      jatos-data:
      jatos-logs:
    EOL

    docker compose -f /root/compose.yaml up -d

    This script will use Docker Compose to set up Traefik and JATOS. It creates a Docker Compose config file under /root/compose.yaml and then runs it with docker compose up.

    Before you can click the Create Droplet button, change my.domain.org and myemail@example.org (in the top of the script) with your own domain name and email address. Your email is needed to get a certificate from Let's Encrypt for encryption. Also, you might want to set JATOS version to a specific release: change latest in the line image: "jatos/jatos:latest".

    Set up your DNS​

    After you've created your Droplet, you still have to point your domain name to your server's IP address. This is what a DNS (Domain Name Service) does and it involves dealing with things like DNS records, especially A records or AAAA records, and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registrar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Restart​

    Then as a last step, after your domain name points to your server's IP, you have to restart your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and uses HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption and your domain name.

    Misc​

    • Let's Encrypt has a rate limit for the number of certificates. If you are not sure and just want to try it out, uncomment the following line in the Initialization script:

      - "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

      This will let you use their staging server that does not have such rate limit - but you won't get a proper certificate either.

    • The Docker Compose config file that is created during the Droplet initialization has the path /root/compose.yaml and the certificate is stored under /root/letsencrypt/.

    • You can configure JATOS by changing the /root/compose.yaml. You can add all command-line arguments of JATOS in the command section of the jatos service_.

      E.g. to add a welcome message on the home page use -Djatos.brandingUrl:

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.brandingUrl=https://mydomain.com/foobar-university-welcome-page.html'
          ...

      E.g. to let JATOS use an external MySQL database use -Djatos.db.url, -Djatos.db.username, -Djatos.db.password, and -Djatos.db.driver (change IP, port, username and password to the ones of your database)

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.db.url=jdbc:mysql://1.2.3.4: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'
          ...
    + \ No newline at end of file diff --git a/3.8.x/JATOS-on-a-server.html b/3.8.x/JATOS-on-a-server.html index 397687967..596371a35 100644 --- a/3.8.x/JATOS-on-a-server.html +++ b/3.8.x/JATOS-on-a-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    And there are dedicated pages for installation with Docker and Docker Compose.

    Installing JATOS as a Internet server usually involves exchanging the embedded database with a MySQL/MariaDB one and setting up a reverse proxy (mostly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.

    Install Java​

    JATOS needs Java 8 or 11 to run (17 is not yet supported). You can install your own Java or get a JATOS that is already bundled with Java.

    Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Run JATOS:

      ./loader.sh start

      And to stop it:

      Usually Ctr+C does the job, but if your JATOS runs in the background:

      ./loader.sh stop

    5. Check JATOS is running correctly:

      Use curl: curl http://localhost:9000/ping should give you pong back

      If you can already access your server from the outside, open JATOS in a browser (the default port is 9000): http://my-IP-or-domain:9000. It should show the JATOS login screen. You can log in with username admin and password admin.

      Check JATOS' Administration page: http://my-IP-or-domain/jatos/admin. Click the Tests button: all tests should show an 'OK'. Click on System Info and check that all is like you configured it.

    6. Always change admin's password

      This can be done in JATOS' GUI:

      1. In a browser go to JATOS' login page http://my-IP-or-domain/jatos
      2. Log in as 'admin' with password 'admin'
      3. Click on Admin (admin) in top-right header
      4. Click Change Password

    [Optional] Install MySQL/MariaDB​

    See JATOS with MySQL

    Configuration​

    These docs have an extra page on JATOS Configuration. E.g. you can add user authentication with ORCID (orcid.org), OpenID Connect (OIDC), LDAP, or Google Sign-in.

    [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    [Optional] Specify the location of JATOS' data folders​

    By default all data folders are located in JATOS installation folder. But sometimes it is better to change the location to better suit your needs, e.g. for easier backups or updates.

    JATOS' data folders (and their path configuration):

    One might want to move all data folders in one extra 'data' folder. E.g. in JATOS' config file the following properties have to be set:

    jatos.studyAssetsRootPath = "/path/to/my/jatos-data-folder/study_assets_root"
    jatos.resultUploads.path =  "/path/to/my/jatos-data-folder/result_uploads"
    jatos.studyLogs.path =      "/path/to/my/jatos-data-folder/study_logs"

    Or with command-line arguments this would be:

    -Djatos.studyAssetsRootPath="/path/to/my/jatos-data-folder/study_assets_root" -Djatos.resultUploads.path="/path/to/my/jatos-data-folder/result_uploads" -Djatos.studyLogs.path="/path/to/my/jatos-data-folder/study_logs"

    [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularly.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the data folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to stop JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    1. JATOS data folders

      JATOS has a couple of data folders. For easier backups it makes sense to have them all in one extra 'data' folder. Then you can just backup this 'data' folder with whatever file backup mechanism suits you best.

    2. Backup MySQL/MariaDB

      If you use a MySQL or MariaDB database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.

    3. 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

    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.

    2. If you specified an extra 'data' folder 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.

    - +
    Skip to main content
    Version: 3.8.x

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    And there are dedicated pages for installation with Docker and Docker Compose.

    Installing JATOS as a Internet server usually involves exchanging the embedded database with a MySQL/MariaDB one and setting up a reverse proxy (mostly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.

    Install Java​

    JATOS needs Java 8 or 11 to run (17 is not yet supported). You can install your own Java or get a JATOS that is already bundled with Java.

    Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Run JATOS:

      ./loader.sh start

      And to stop it:

      Usually Ctr+C does the job, but if your JATOS runs in the background:

      ./loader.sh stop

    5. Check JATOS is running correctly:

      Use curl: curl http://localhost:9000/ping should give you pong back

      If you can already access your server from the outside, open JATOS in a browser (the default port is 9000): http://my-IP-or-domain:9000. It should show the JATOS login screen. You can log in with username admin and password admin.

      Check JATOS' Administration page: http://my-IP-or-domain/jatos/admin. Click the Tests button: all tests should show an 'OK'. Click on System Info and check that all is like you configured it.

    6. Always change admin's password

      This can be done in JATOS' GUI:

      1. In a browser go to JATOS' login page http://my-IP-or-domain/jatos
      2. Log in as 'admin' with password 'admin'
      3. Click on Admin (admin) in top-right header
      4. Click Change Password

    [Optional] Install MySQL/MariaDB​

    See JATOS with MySQL

    Configuration​

    These docs have an extra page on JATOS Configuration. E.g. you can add user authentication with ORCID (orcid.org), OpenID Connect (OIDC), LDAP, or Google Sign-in.

    [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    [Optional] Specify the location of JATOS' data folders​

    By default all data folders are located in JATOS installation folder. But sometimes it is better to change the location to better suit your needs, e.g. for easier backups or updates.

    JATOS' data folders (and their path configuration):

    One might want to move all data folders in one extra 'data' folder. E.g. in JATOS' config file the following properties have to be set:

    jatos.studyAssetsRootPath = "/path/to/my/jatos-data-folder/study_assets_root"
    jatos.resultUploads.path =  "/path/to/my/jatos-data-folder/result_uploads"
    jatos.studyLogs.path =      "/path/to/my/jatos-data-folder/study_logs"

    Or with command-line arguments this would be:

    -Djatos.studyAssetsRootPath="/path/to/my/jatos-data-folder/study_assets_root" -Djatos.resultUploads.path="/path/to/my/jatos-data-folder/result_uploads" -Djatos.studyLogs.path="/path/to/my/jatos-data-folder/study_logs"

    [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularly.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the data folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to stop JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    1. JATOS data folders

      JATOS has a couple of data folders. For easier backups it makes sense to have them all in one extra 'data' folder. Then you can just backup this 'data' folder with whatever file backup mechanism suits you best.

    2. Backup MySQL/MariaDB

      If you use a MySQL or MariaDB database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.

    3. 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

    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.

    2. If you specified an extra 'data' folder 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/3.8.x/JATOS-with-Apache.html b/3.8.x/JATOS-with-Apache.html index 0191b3a8c..f6b0e1f45 100644 --- a/3.8.x/JATOS-with-Apache.html +++ b/3.8.x/JATOS-with-Apache.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS with Apache

    This is an example of a configuration of Apache 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 from the Electronic Frontier Foundation.

    You have to add some modules to Apache to get it working:

    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 <Location "/jatos"> and config your local network. This will restrict the access to JATOS' GUI (every URL starting with /jatos) to the local network.

    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # 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/
    </VirtualHost>
    - +
    Skip to main content
    Version: 3.8.x

    JATOS with Apache

    This is an example of a configuration of Apache 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 from the Electronic Frontier Foundation.

    You have to add some modules to Apache to get it working:

    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 <Location "/jatos"> and config your local network. This will restrict the access to JATOS' GUI (every URL starting with /jatos) to the local network.

    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # 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/
    </VirtualHost>
    + \ No newline at end of file diff --git a/3.8.x/JATOS-with-Docker-Compose.html b/3.8.x/JATOS-with-Docker-Compose.html index 0c8f1ea68..765aca987 100644 --- a/3.8.x/JATOS-with-Docker-Compose.html +++ b/3.8.x/JATOS-with-Docker-Compose.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS with Docker Compose

    Docker 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 that you can clone and then change them to your needs to get a JATOS installation running with docker compose. 

    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 starts three services:

    1. Nginx as a reverse proxy that does encryption (HTTPS)
    2. JATOS
    3. 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
    2. jatos-logs - for JATOS logs (not necessary if you log to stdout)
    3. jatos-db - where MySQL stores its data

    Up​

    Go into the cloned folder and start the services with:

    docker compose -f compose.yaml up

    If everything went smoothly, you will now see the JATOS login page under: 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. 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) 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 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. 

    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 with --skip-log-bin in db's command section.

    Check JATOS with MySQL for more information.

    JATOS configuration​

    Have a look at JATOS Configuration.

    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 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 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.

    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. 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.

    - +
    Skip to main content
    Version: 3.8.x

    JATOS with Docker Compose

    Docker 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 that you can clone and then change them to your needs to get a JATOS installation running with docker compose. 

    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 starts three services:

    1. Nginx as a reverse proxy that does encryption (HTTPS)
    2. JATOS
    3. 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
    2. jatos-logs - for JATOS logs (not necessary if you log to stdout)
    3. jatos-db - where MySQL stores its data

    Up​

    Go into the cloned folder and start the services with:

    docker compose -f compose.yaml up

    If everything went smoothly, you will now see the JATOS login page under: 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. 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) 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 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. 

    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 with --skip-log-bin in db's command section.

    Check JATOS with MySQL for more information.

    JATOS configuration​

    Have a look at JATOS Configuration.

    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 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 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.

    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. 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.

    + \ No newline at end of file diff --git a/3.8.x/JATOS-with-MySQL.html b/3.8.x/JATOS-with-MySQL.html index 5e6421bdf..630150976 100644 --- a/3.8.x/JATOS-with-MySQL.html +++ b/3.8.x/JATOS-with-MySQL.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS with MySQL

    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. One way to set up MySQL:

    1. Install MySQL

      E.g. on Ubuntu

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      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.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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:

        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.

    2. 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:

        -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:

        ./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).

    3. 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:

      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):

    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.

    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). 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:

    # 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 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:

    max_allowed_packet=64M

    You have to restart the database for the changes to take effect.

    - +
    Skip to main content
    Version: 3.8.x

    JATOS with MySQL

    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. One way to set up MySQL:

    1. Install MySQL

      E.g. on Ubuntu

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      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.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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:

        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.

    2. 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:

        -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:

        ./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).

    3. 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:

      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):

    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.

    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). 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:

    # 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 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:

    max_allowed_packet=64M

    You have to restart the database for the changes to take effect.

    + \ No newline at end of file diff --git a/3.8.x/JATOS-with-Nginx.html b/3.8.x/JATOS-with-Nginx.html index f8aac8fa0..eb9c91ef6 100644 --- a/3.8.x/JATOS-with-Nginx.html +++ b/3.8.x/JATOS-with-Nginx.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    JATOS with Nginx

    Here is an example for a configuration of Nginx 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 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.

    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;
            }
        }
    }
    - +
    Skip to main content
    Version: 3.8.x

    JATOS with Nginx

    Here is an example for a configuration of Nginx 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 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.

    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/3.8.x/JATOS_Configuration.html b/3.8.x/JATOS_Configuration.html index 73364ec92..8f25a21d6 100644 --- a/3.8.x/JATOS_Configuration.html +++ b/3.8.x/JATOS_Configuration.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    JATOS Configuration

    JATOS' properties can be configured in three different ways:

    1. via a config file (named jatos.conf or production.conf)
    2. via command-line arguments
    3. 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. 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:

    ./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:

      jatos.http.address = 1.2.3.4
      jatos.http.port = 80

    2. 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:

      -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:

      play.server.http.idleTimeout = 100s

    2. Via command-line argument -Dplay.server.http.idleTimeout

      Example:

      -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:

      play.server.akka.requestTimeout = 100s

    2. Via command-line argument -Dplay.server.akka.requestTimeout

      Example:

      -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 (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:

      jatos.urlBasePath = "/mybasepath/"

    2. Via command-line arguments

      • For v3.8.1 and lower) -Dplay.http.context
      • For v3.8.2 and higher) -Djatos.urlBasePath
      -Djatos.urlBasePath="/mybasepath/"

    3. Via environment variable JATOS_URL_BASE_PATH

      JATOS_URL_BASE_PATH="/mybasepath/"

    X-Frame-Options header​

    The X-Frame-Options header can be used to allow or disallow embedding a JATOS study in an 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:

      play.filters.headers.frameOptions = null

    2. Via command-line argument -Dplay.filters.headers.frameOptions

      Example:

      -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

      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

      jatos.studyAssetsRootPath = "/path/to/my/assets/root/folder"

    2. Via command-line argument -Djatos.studyAssetsRootPath

      -Djatos.studyAssetsRootPath="/path/to/my/assets/root/folder"

    3. Via environment variable JATOS_STUDY_ASSETS_ROOT_PATH

      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

      jatos.tmpPath = "/my/tmp/dir"

    2. Via command-line argument -Djatos.tmpPath

      -Djatos.tmpPath="/my/tmp/dir"

    3. Via environment variable JATOS_TMP_PATH

      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.

    Application logs path​

    The application logs are by default in the JATOS folder under ./logs.

    1. Via config file property jatos.logs.path

      jatos.logs.path = "/my/dir/logs"

    2. Via command-line argument -Djatos.logs.path

      -Djatos.logs.path="/my/dir/logs"

    3. Via environment variable JATOS_LOGS_PATH

      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

      jatos.logs.filename = "myFilename"

    2. Via command-line argument -Djatos.logs.filename

      -Djatos.logs.filename="myFilename"

    3. Via environment variable JATOS_LOGS_FILENAME

      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

      jatos.logs.appender = ASYNCSTDOUT

    2. Via command-line argument -Djatos.logs.appender

      -Djatos.logs.appender=ASYNCSTDOUT

    3. Via environment variable JATOS_LOGS_APPENDER

      JATOS_LOGS_APPENDER=ASYNCSTDOUT

    Study logs​

    Every study stored in JATOS has its own study log (more info). 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. .

    Enable/disable study logging​

    By default study logging is enabled.

    1. Via config file property jatos.studyLogs.enabled

      jatos.studyLogs.enabled = false

    2. Via command-line argument -Djatos.studyLogs.enabled

      -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

      jatos.studyLogs.path = "/path/to/my/jatos_study_logs"

    2. Via command-line argument -Djatos.studyLogs.path

      -Djatos.studyLogs.path="/path/to/my/jatos_study_logs"

    3. Via environment variable JATOS_STUDY_LOGS_PATH

      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

      jatos.studyMembers.allowAddAllUsers = true

    2. Via command-line argument -Djatos.studyMembers.allowAddAllUsers

      -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

      jatos.maxResultsDbQuerySize = 5

    2. Via command-line argument -Djatos.maxResultsDbQuerySize

      -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

      jatos.resultData.maxSize = 10MB

    2. Via command-line argument -Djatos.resultData.maxSize

      -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

      jatos.resultUploads.enabled = false

    2. Via command-line argument -Djatos.resultUploads.enabled

      -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

      jatos.resultUploads.path = "/path/to/my/jatos_result_uploads"

    2. Via command-line argument -Djatos.resultUploads.path

      -Djatos.resultUploads.path="/path/to/my/jatos_result_uploads"

    3. Via environment variable JATOS_RESULT_UPLOADS_PATH

      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

      jatos.resultUploads.maxFileSize = 100MB

    2. Via command-line argument -Djatos.resultUploads.maxFileSize

      -Djatos.resultUploads.maxFileSize=100MB

    3. Via environment variable JATOS_RESULT_UPLOADS_MAX_FILE_SIZE

      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

      jatos.resultUploads.limitPerStudyRun = 100MB

    2. Via command-line argument -Djatos.resultUploads.limitPerStudyRun

      -Djatos.resultUploads.limitPerStudyRun=100MB

    3. Via environment variable JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN

      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

      jatos.user.role.allowSuperuser = true

    2. Via command-line argument -Djatos.user.role.allowSuperuser

      -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).

    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

      jatos.user.authentication.ldap.url = "ldap://my.ldap.org:389"

    2. Via command-line argument -Djatos.user.authentication.ldap.url

      -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

      jatos.user.authentication.ldap.basedn = "dc=example,dc=com"

    2. Via command-line argument -Djatos.user.authentication.ldap.basedn

      -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

      jatos.user.authentication.ldap.admin.dn = "cn=read-only-admin,dc=example,dc=com"
      jatos.user.authentication.ldap.admin.password = "mypassword"

    2. Via command-line arguments -Djatos.user.authentication.ldap.admin.dn and -Djatos.user.authentication.ldap.admin.password

      -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

      jatos.user.authentication.ldap.timeout = 10000

    2. Via command-line argument -Djatos.user.authentication.ldap.timeout

      -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.

    1. Via config file property jatos.user.authentication.oauth.googleClientId

      jatos.user.authentication.oauth.googleClientId = "1234567890-abc123abc123.apps.googleusercontent.com"

    2. Via command-line argument -Djatos.user.authentication.oauth.googleClientId

      -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.

    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

      jatos.user.authentication.oidc.discoveryUrl = "http://myOidcProvider/.well-known/openid-configuration"

    2. Via command-line argument -Djatos.user.authentication.oidc.discoveryUrl

      -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

      jatos.user.authentication.oidc.clientId = "myClientId"

    2. Via command-line argument -Djatos.user.authentication.oidc.clientId

      -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

      jatos.user.authentication.oidc.clientSecret = "myClientSecret"

    2. Via command-line argument -Djatos.user.authentication.oidc.clientSecret

      -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

      jatos.user.authentication.oidc.idTokenSigningAlgorithm = "ES512"

    2. Via command-line argument -Djatos.user.authentication.oidc.idTokenSigningAlgorithm

      -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

      jatos.user.authentication.oidc.signInButtonText = "Sign in with ABC university"

    2. Via command-line argument -Djatos.user.authentication.oidc.signInButtonText

      -Djatos.user.authentication.oidc.signInButtonText="Sign in with ABC university"

    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

      jatos.user.authentication.oidc.signInButtonLogoUrl = "http://somedomain/logo.svg"

    2. Via command-line argument -Djatos.user.authentication.oidc.signInButtonLogoUrl

      -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

      jatos.user.authentication.oidc.successFeedback = "You successfully signed in with ABC university"

    2. Via command-line argument -Djatos.user.authentication.oidc.successFeedback

      -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. Internally ORCID uses OpenId Connect.

    ORCID client ID​

    Specifies your ORCID client ID.

    1. Via config file property jatos.user.authentication.orcid.clientId

      jatos.user.authentication.orcid.clientId = "APP-ABCDEFGHIJKLMNOP"

    2. Via command-line argument -Djatos.user.authentication.orcid.clientId

      -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

      jatos.user.authentication.orcid.clientSecret = "1234abcd-12ab-12ab-12ab-123456abcdef"

    2. Via command-line argument -Djatos.user.authentication.orcid.clientSecret

      -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

      jatos.user.password.length = 8

    2. Via command-line argument -Djatos.user.password.length

      -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

      jatos.user.password.strength = 3

    2. Via command-line argument -Djatos.user.password.strength

      -Djatos.user.password.strength=3

    Database​

    See JATOS with MySQL.

    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

      jatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"

    2. Via command-line argument -Djatos.db.url

      -Djatos.db.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"

    3. Via environment variable JATOS_DB_URL

      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

      jatos.db.username = "myusername"
      jatos.db.password = "mypassword"

    2. Via command-line argument -Djatos.db.username and -Djatos.db.password

      -Djatos.db.username = "myusername" -Djatos.db.password = "mypassword"

    3. Via environment variable JATOS_DB_USERNAME and JATOS_DB_PASSWORD

      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

      jatos.db.driver = "com.mysql.cj.jdbc.Driver"

    2. Via command-line argument -Djatos.db.driver

      -Djatos.db.driver="com.mysql.cj.jdbc.Driver"

    3. Via environment variable JATOS_DB_DRIVER

      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

      jatos.multiNode = true

    2. Via command-line argument -Djatos.multiNode

      -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

      jatos.userSession.timeout = 180

    2. Via command-line argument -Djatos.userSession.timeout

      -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

      jatos.userSession.inactivity = 120

    2. Via command-line argument -Djatos.userSession.inactivity

      -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

      play.http.session.secure = true

    2. Via command-line argument -Dplay.http.session.secure

      -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

      jatos.idCookies.secure = true

    2. Via command-line argument -Djatos.idCookies.secure

      -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

      jatos.idCookies.sameSite = "Lax"

    2. Via command-line argument -Djatos.idCookies.sameSite

      -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

      play.pidfile.path = "/var/run/jatos.pid"

    2. Via command-line argument -Dplay.pidfile.path

      -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). If left empty ("") the default welcome message is shown. Default is empty.

    1. Via config file property jatos.brandingUrl

      jatos.brandingUrl = "https://mydomain.com/foobar-university-welcome-page.html"

    2. Via command-line argument -Djatos.brandingUrl

      -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

      jatos.termsOfUseUrl = "https://mydomain.com/my-terms-of-use.html"

    2. Via command-line argument -Djatos.termsOfUseUrl

      -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

      jatos.studyAdmin.showStudyAssetsSize = false # Default is true
      jatos.studyAdmin.showResultDataSize = true # Default is false
      jatos.studyAdmin.showResultFileSize = true # Default is false

    2. Via command-line arguments -Djatos.studyAdmin.showStudyAssetsSize, -Djatos.studyAdmin.showResultDataSize, and -Djatos.studyAdmin.showResultFileSize

      -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

      jatos.api.allowed = false

    2. Via command-line argument -Djatos.api.allowed

      -Djatos.api.allowed = false
    - +due to a slow database or file system.

    1. Via config file properties jatos.studyAdmin.showStudyAssetsSize, jatos.studyAdmin.showResultDataSize, and jatos.studyAdmin.showResultFileSize

      jatos.studyAdmin.showStudyAssetsSize = false # Default is true
      jatos.studyAdmin.showResultDataSize = true # Default is false
      jatos.studyAdmin.showResultFileSize = true # Default is false

    2. Via command-line arguments -Djatos.studyAdmin.showStudyAssetsSize, -Djatos.studyAdmin.showResultDataSize, and -Djatos.studyAdmin.showResultFileSize

      -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

      jatos.api.allowed = false

    2. Via command-line argument -Djatos.api.allowed

      -Djatos.api.allowed = false
    + \ No newline at end of file diff --git a/3.8.x/Manage-Results.html b/3.8.x/Manage-Results.html index 0bf13de6a..ac3f50ae4 100644 --- a/3.8.x/Manage-Results.html +++ b/3.8.x/Manage-Results.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Manage Results

    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

    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

    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

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export Results​

    Results View screenshot

    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

    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).

    Export Result Metadata​

    Results View screenshot

    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.

    Export Result Data​

    Results View screenshot

    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

    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.

    Delete Results​

    Results View screenshot

    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

    • 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.

    • 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 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 (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 or jatos.abortStudy.

    - +
    Skip to main content
    Version: 3.8.x

    Manage Results

    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

    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

    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

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export Results​

    Results View screenshot

    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

    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).

    Export Result Metadata​

    Results View screenshot

    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.

    Export Result Data​

    Results View screenshot

    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

    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.

    Delete Results​

    Results View screenshot

    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

    • 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.

    • 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 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 (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 or jatos.abortStudy.

    + \ No newline at end of file diff --git a/3.8.x/OSWeb-and-JATOS.html b/3.8.x/OSWeb-and-JATOS.html index 59efe4ec7..3f4245a1f 100644 --- a/3.8.x/OSWeb-and-JATOS.html +++ b/3.8.x/OSWeb-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    - +
    Skip to main content
    Version: 3.8.x

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    + \ No newline at end of file diff --git a/3.8.x/Papers-Citing-JATOS.html b/3.8.x/Papers-Citing-JATOS.html index f5cbfe332..e05439626 100644 --- a/3.8.x/Papers-Citing-JATOS.html +++ b/3.8.x/Papers-Citing-JATOS.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Papers citing JATOS

    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.)

    Please cite us 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 on how (much) you use JATOS (ca. 3 min). It’s very important for us!

    2024​

    Brouwer, J., van den Berg, F., Knooihuizen, R., Loerts, H., & Keijzer, M. (2024). The effects of language learning on cognitive functioning and psychosocial well-being in cognitively healthy older adults: A semi-blind randomized controlled trial. Aging, Neuropsychology, and Cognition. DOI

    Frugarello, P., Rusconi, E., Job, R. (2024) The label-feedback effect is influenced by target category in visual search. PLoS ONE. DOI

    Bauer, R., Jansen, P. (2024) A short mindfulness induction might increase women’s mental rotation performance. Consciousness and Cognition DOI

    Xue, S., Gao, X., Wu, Y., Sun, J., Yang, W., Li, X., Ke, S., Yang, L., Jin, H., & Chen, S. (2024). Effects of Theme, Form, and Language on Poetry Reading: Evidence From Chinese ESL Learners. Empirical Studies of the Arts. DOI

    Niedernhuber M, Streicher J, Leggenhager B, Bekinschtein TA. (2024) Attention and Interoception Alter Perceptual and Neural Pain Signatures-A Case Study. J Pain Res. DOI

    Schmerwitz, C., Kopp, B. (2024) The future of neuropsychology is digital, theory-driven, and Bayesian: a paradigmatic study of cognitive flexibility. Frontiers in Psychology DOI

    Loaiza, V.M., Souza, A.S. (2024) Active maintenance in working memory reinforces bindings for future retrieval from episodic long-term memory. Mem Cogn. DOI

    Winkelmair, A., Jansen, P. (2024) Can a mindfulness-based training influence explicit and implicit attitudes, as well as sustainable nutrition behaviors, particularly in relation to vegetarianism?. Appetite DOI

    Contemori G., Saccani M.S., Bonato M. (2024) Cognitive-Cognitive Dual-task in aging: A cross-sectional online study. PLoS ONE. DOI

    Gemignani, M., Giannotti, M., Rigo, P. et al. (2024) Neither Parents’ Sex Nor the Type of Family Modulates Attentional Bias Toward Infant Faces: A Preliminary Study in Different-Sex and Same-Sex Parents. Arch Sex Behav. DOI

    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

    Berkovich, R., & Meiran, N. (2024). Both pleasant and unpleasant emotional feelings follow Weber’s law but it depends how you ask. Emotion DOI

    Oz-Cohen, E., Berkovich, R. & Meiran, N. (2024) Bumpy ride ahead: Anticipated effort as emotional evidence?. Cogn Affect Behav Neurosci. DOI

    van Moorselaar, D., & Theeuwes, J. (2024). Transfer of statistical learning between tasks. Journal of Experimental Psychology: Human Perception and Performance. DOI

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Theeuwes, J., Huang, C., Frings, C., & van Moorselaar, D. (2024). Statistical learning of motor preparation. Journal of Experimental Psychology: Human Perception and Performance. DOI

    Corradi G, Aguilar P, Aguiar F, Olivera-La Rosa A (2024) Age and moral disgust: An experimental priming effects vignette study. PLoS ONE DOI

    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

    Bognar, M., Szekely, Z., Varga, M.A. et al. (2024 )Cognitive control adjustments are dependent on the level of conflict. Sci Rep DOI

    van Moorselaar D, Theeuwes J. (2024) Spatial transfer of object-based statistical learning. Atten Percept Psychophys DOI

    Lallement, C., Lemaire, P. (2024) Are There Age-Related Differences in Effects of Positive and Negative Emotions in Arithmetic? Experimental Psychology DOI

    Vandendaele, A., Prutean, N. and Declerck, M. (2024). A Blessing in Disguise: Flanking Words Can Cancel Language Switch Costs. Journal of Cognition DOI

    Moore, C.M., Zheng, Q. (2024) Limited midlevel mediation of visual crowding: Surface completion fails to support uncrowding. Journal of Vision DOI

    Oppenheim, G.M., Nozari, N. (2024) Similarity-induced interference or facilitation in language production reflects representation, not selection. Cognition DOI

    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

    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

    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

    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

    Mu, Y., Schubö, A. & Tünnermann, J. (2024) Adapting attentional control settings in a shape-changing environment. Atten Percept Psychophys. DOI

    Shyr, M.C., Joshi, S.S. (2024) A Case Study of the Validity of Web-based Visuomotor Rotation Experiments. J Cogn Neurosci DOI

    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

    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

    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

    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

    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

    Curzel, F., Carraturo, G., Ripollés, P., & Ferreri, L. (2023). Better off alone? When sharing music reduces pleasure responses. Advances in Cognitive Psychology. DOI

    Fahnenstich, H., Rieger, T., Roesler, E. (2023). Trusting under risk – comparing human to AI decision support agents. Computers in Human Behavior DOI

    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

    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

    Palmer, C. J., Kim, P., & Clifford, C. W. G. (2023). Gaze behavior as a visual cue to animacy. Journal of Experimental Psychology: General. DOI

    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

    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

    Wang, X., Li, X., Yin, Z., Wu, Y., & Liu, J. (2023). Emotional intelligence of Large Language Models. Journal of Pacific Rim Psychology. DOI

    Marks, R.A., Eggleston, R., Kovelman, I. (2023) Brain bases of morphological awareness and longitudinal word reading outcomes. Journal of Experimental Child Psychology. DOI

    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

    Oberholzer, Y., Olschewski, S., Scheibehenne, B. Complexity Aversion in Risky Choices and Valuations: Moderators and Possible Causes. Journal of Economic Psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    Vandendaele, A., & Grainger, J. (2023). Lexical competition in the flankers task revised. PLoS one DOI

    Labaronne, M., Ferreri, L. & Plancher, G. (2023) How do intentions modulate the effect of working memory on long-term memory? Psychon Bull Rev. DOI

    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

    Constant, M., Pereira, M., Faivre, N. et al. (2023) Prior information differentially affects discrimination decisions and subjective confidence reports. Nat Commun. DOI

    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

    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

    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

    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

    Sobczak, A., Bunzeck, N. (2023) Effects of positive and negative social feedback on motivation, evaluative learning, and socio-emotional processing. npj Sci. Learn. DOI

    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

    Ivanov, Y., Theeuwes, J. & Bogaerts, L. (2023) Reliability of individual differences in distractor suppression driven by statistical learning. Behav Res. DOI

    Wang-Ly, Nathan and Newell, Ben R. (2023) Uncertain goals and savings adequacy: Contrasting economic and psychological perspectives. SSRN DOI

    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

    de Waard, J., van Moorselaar, D., Bogaerts, L. et al. (2023) Statistical learning of distractor locations is dependent on task context. Sci Rep DOI

    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

    Jansen, P., Rahe, M., Hoja, S. et al. (2023) Are Character Strengths and Attitudes towards Vegetarian Food Related? Int J Appl Posit Psychol. DOI

    Kahan, T.A., Smith, Z.P. (2023) Effects of alerting signals on the spatial Stroop effect: evidence for modality differences. Psychological Research. DOI

    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

    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

    Xie, T., Fu, S. & Mento, G. (2023) Faces do not guide attention in an object-based facilitation manner. Atten Percept Psychophys. DOI

    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

    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

    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

    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

    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

    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

    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

    Gao, Y., de Waard, J. & Theeuwes, J. (2023) Learning to suppress a location is configuration-dependent. Atten Percept Psychophys DOI

    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

    Ng, D. W., Lee, J. C., & Lovibond, P. F. (2023). Unidirectional rating scales overestimate the illusory causation phenomenon. Quarterly Journal of Experimental Psychology DOI

    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

    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

    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

    Tian, J., Ren, K., Gunderson, EA. (2023) Verbal labels influence children's processing of decimal magnitudes. Journal of Applied Developmental Psychology DOI

    Bognar, M., Gyurkovics, M., van Steenbergen, H. & Aczel, B. (2023) Phasic affective signals by themselves do not regulate cognitive control. Cognition and Emotion DOI

    Huang, C., Donk, M. & Theeuwes, J. (2023) Attentional suppression is in place before display onset. Atten Percept Psychophys. DOI

    Salava, A, Salmela, V. (2023) Perceptual learning in dermatology—A Finnish cohort study of undergraduate medical students. J Eur Acad Dermatol Venereol. DOI

    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

    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

    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

    Dijkstra, N., Fleming, S.M. (2023) Subjective signal strength distinguishes reality from imagination. Nat Commun DOI

    Guseva, M., Bogler, C., Allefeld C., Haynes JD. (2023) Instruction effects on randomness in sequence generation. Frontiers in Psychology. DOI

    van Moorselaar, D., & Theeuwes, J. (2023). Statistical Learning Within Objects. Psychological Science DOI

    Lu, Z., van Zoest, W. (2023) Combining social cues in attention: Looking at gaze, head, and pointing cues. Atten Percept Psychophys. DOI

    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

    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

    Reichardt, R., Polner, B., & Simor, P. (2023). Influencing prior knowledge through a short reading impacts curiosity and learning. Applied Cognitive Psychology DOI

    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

    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

    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

    Lee, M.D., Stark, C.E.L. (2023) Bayesian modeling of the Mnemonic Similarity Task using multinomial processing trees. Behaviormetrika DOI

    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

    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

    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

    Zoefel B, Gilbert RA, Davis MH (2023) Intelligibility improves perception of timing changes in speech. PLoS ONE DOI

    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

    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

    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

    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

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys DOI

    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

    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

    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

    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

    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

    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

    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

    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

    Wittmann BC, Şatırer Y. (2022) Decreased associative processing and memory confidence in aphantasia. Learn Mem. DOI

    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

    Mueckstein, M., Heinzel, S., Granacher, U., Brahms, M., Rapp, MA., Stelzel, C. (2022) Modality-specific effects of mental fatigue in multitasking, Acta Psychologica DOI

    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

    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

    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

    Radović T, Rieger T and Manzey D (2022) A global and local perspective of interruption frequency in a visual search task. Front. Psychol. DOI

    Vos, M., Minor, S., & Ramchand, G. C. (2022). Comparing infrared and webcam eye tracking in the Visual World Paradigm. Glossa Psycholinguistics DOI

    Tsang, K. Y., & Mannion, D. J. (2022). Relating Sound and Sight in Simulated Environments. Multisensory Research DOI

    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

    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

    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

    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

    Contemori, G., Saccani, MS., Bonato, M. (2022) Multitasking Effects on Perception and Memory in Older Adults. Vision DOI

    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

    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

    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

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    - +Language Sciences DOI

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    + \ No newline at end of file diff --git a/3.8.x/Restricting-study-flow.html b/3.8.x/Restricting-study-flow.html index 32b77fea4..19746d26a 100644 --- a/3.8.x/Restricting-study-flow.html +++ b/3.8.x/Restricting-study-flow.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Restricting study flow - reloading, linear studies, single-use workers and previews

    Intro: Restricting study flow​

    Let's first say what we understand under the study flow:

    Study flow - the intended order of a study's componenents 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

    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

    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 and about study links.

    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

    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.

    - +
    Skip to main content
    Version: 3.8.x

    Restricting study flow - reloading, linear studies, single-use workers and previews

    Intro: Restricting study flow​

    Let's first say what we understand under the study flow:

    Study flow - the intended order of a study's componenents 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

    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

    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 and about study links.

    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

    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.

    + \ No newline at end of file diff --git a/3.8.x/Run-an-experiment-with-JATOS-Workflow.html b/3.8.x/Run-an-experiment-with-JATOS-Workflow.html index d4f295b60..3e5fe57ae 100644 --- a/3.8.x/Run-an-experiment-with-JATOS-Workflow.html +++ b/3.8.x/Run-an-experiment-with-JATOS-Workflow.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Run an experiment with JATOS - Workflow

    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

    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. -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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    - +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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    + \ No newline at end of file diff --git a/3.8.x/Run-your-Study-with-Study-Links.html b/3.8.x/Run-your-Study-with-Study-Links.html index 45c15e351..64ad72003 100644 --- a/3.8.x/Run-your-Study-with-Study-Links.html +++ b/3.8.x/Run-your-Study-with-Study-Links.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Run your Study with Study Links

    Study Links in JATOS is the name of a page where one can generate study links for your particpants to run your study. You can also organize your participants into batches and handle their results there. In earlier versions of JATOS it was called Worker and Batch Manager.

    To get to the Study Links page press on the button with the same name in your study's page:

    Study Links Button screenshot

    This Study Links page has only one batch, the 'Default' one. A batch can have study links of different type, e.g. Personal Single, Personal Multiple etc:

    Study Links page screenshot

    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.

    Study Links page screenshot

    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

    You can de-/activate a study link type by clicking in the checkboxes in the left of each row (red box). Decactived types cannot be used to run a study. Always check before you send out study links that the corresponding types are activated.

    Study Links page screenshot

    Personal type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    1. This button creates one study link without a comment. This button is a shortcut to the 'New Study Links' button.
    2. 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 destinguish your study links. You can create Personal type study links in bulk by changing the Amount value.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. 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).
    6. 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

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and create study links is described in its own page: Connect to Mechanical Turk.

    Study Entry Page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    If you toogle 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

    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 curiousity) 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

    The advantage of using the Study Entry page with the study codes is similar to a 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

    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

    • 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 a JSON input similar to the one in the study or component properties. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    - +
    Skip to main content
    Version: 3.8.x

    Run your Study with Study Links

    Study Links in JATOS is the name of a page where one can generate study links for your particpants to run your study. You can also organize your participants into batches and handle their results there. In earlier versions of JATOS it was called Worker and Batch Manager.

    To get to the Study Links page press on the button with the same name in your study's page:

    Study Links Button screenshot

    This Study Links page has only one batch, the 'Default' one. A batch can have study links of different type, e.g. Personal Single, Personal Multiple etc:

    Study Links page screenshot

    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.

    Study Links page screenshot

    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

    You can de-/activate a study link type by clicking in the checkboxes in the left of each row (red box). Decactived types cannot be used to run a study. Always check before you send out study links that the corresponding types are activated.

    Study Links page screenshot

    Personal type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    1. This button creates one study link without a comment. This button is a shortcut to the 'New Study Links' button.
    2. 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 destinguish your study links. You can create Personal type study links in bulk by changing the Amount value.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. 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).
    6. 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

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and create study links is described in its own page: Connect to Mechanical Turk.

    Study Entry Page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    If you toogle 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

    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 curiousity) 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

    The advantage of using the Study Entry page with the study codes is similar to a 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

    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

    • 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 a JSON input similar to the one in the study or component properties. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    + \ No newline at end of file diff --git a/3.8.x/Session-Data-Three-Types.html b/3.8.x/Session-Data-Three-Types.html index cc49e9ce1..d55d952e0 100644 --- a/3.8.x/Session-Data-Three-Types.html +++ b/3.8.x/Session-Data-Three-Types.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Session Data - Three Types

    When to use the sessions?​

    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 JSON Input Data instead.


    Comparative Overview​

    Batch SessionGroup SessionStudy Session
    Scope (accesible by)All workers in a batchAll workers in a groupAll components in a study
    UsageExchange and store data relevant for all members of a batchExchange and temporarily store data relevant for all members of a groupExchange 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 batchStore choices of the two members of a Prisoner's Dilemma gamePass on correct answers between components; Keep track of the number of iterations of a given component that is repeated
    LifetimeSurvives after all workers finished their studiesAutomatically deleted once the group is finishedDeleted once the worker finished the study - Hence temporary
    Updated when and viaAny time you call one of the jatos.batchSession functionsAny time you call one of the jatos.groupSession functionsAt the end of each component or if you call jatos.setStudySessionData
    Visible and editable from JATOS' GUIyesnono
    Requires WebSocketsyesyesno
    Included in exported studiesnonono

    Example Study​

    We have an example study, 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".

    2. Run the study once: easiest is as a JATOS worker (just click 'Run' on the study bar, not on any of the component bars).

    3. 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

    4. 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

    5. 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. 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 -Second component screenshot

    - +Second component screenshot

    + \ No newline at end of file diff --git a/3.8.x/Study-Log.html b/3.8.x/Study-Log.html index 0b64996c6..5e81a759c 100644 --- a/3.8.x/Study-Log.html +++ b/3.8.x/Study-Log.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Study Log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    - +
    Skip to main content
    Version: 3.8.x

    Study Log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    + \ No newline at end of file diff --git a/3.8.x/Submit-and-upload-data-to-the-server.html b/3.8.x/Submit-and-upload-data-to-the-server.html index cb145c949..5838dc6e4 100644 --- a/3.8.x/Submit-and-upload-data-to-the-server.html +++ b/3.8.x/Submit-and-upload-data-to-the-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    - +
    Skip to main content
    Version: 3.8.x

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    + \ No newline at end of file diff --git a/3.8.x/Tips-and-Tricks.html b/3.8.x/Tips-and-Tricks.html index 9ab515383..f29a073ea 100644 --- a/3.8.x/Tips-and-Tricks.html +++ b/3.8.x/Tips-and-Tricks.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Tips & Tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    - +
    Skip to main content
    Version: 3.8.x

    Tips & Tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    + \ No newline at end of file diff --git a/3.8.x/Troubleshooting.html b/3.8.x/Troubleshooting.html index e1bd0110f..6000cbf33 100644 --- a/3.8.x/Troubleshooting.html +++ b/3.8.x/Troubleshooting.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    - +
    Skip to main content
    Version: 3.8.x

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    + \ No newline at end of file diff --git a/3.8.x/Update-JATOS.html b/3.8.x/Update-JATOS.html index 8017a4b30..d477a783c 100644 --- a/3.8.x/Update-JATOS.html +++ b/3.8.x/Update-JATOS.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Update JATOS

    We'll periodically update JATOS with new features and bug fixes. We recommend you stay up to date with the latest release. 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:

    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

      Sometimes your JATOS is not able to receive data about new releases. If this is the case 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.

    2. 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.

    3. After download is complete, you will be asked again for confirmation. Optionally you can do a backup: JATOS will copy the content of its own installation folder into a folder with the name backup_x.x.x (x.x.x is the version before the update). This will usually include your embedded H2 database, your study assets and logs - but not your MySQL database (should you have one). If anything goes wrong in the auto-update, you have everything in this backup folder to start the old JATOS again. This backup will use up disk space (that is why it is not selected by default).

      Update notification Schreenshot

    4. 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.

    5. 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 and enforces an update to this version.

    E.g. if the version you want to update to is v3.7.4 (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.7.4

    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.
    2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
    3. Stop the old JATOS and start the new JATOS.
    4. 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
    2. All your studies' and components' properties
    3. The properties of the first (Default) batch

    What will be lost:

    1. All result data and files will be lost
    2. All workers in all batches (including Default batch)
    3. All batches other than the Default batch
    4. Any configuration you did in jatos.conf
    5. 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.
    2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
    3. 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.
    4. Start the new JATOS.

    What will be transferred:

    1. All study assets
    2. All your study and component properties
    3. All batches, together with their workers, and generated study links
    4. All result data and files
    5. All study logs
    6. All logs
    7. JATOS' configuration (as long as it is done in the configuration file)

    What will be lost: -nothing

    - +nothing

    + \ No newline at end of file diff --git a/3.8.x/Use-Prolific.html b/3.8.x/Use-Prolific.html index 712042d47..c8fc737ae 100644 --- a/3.8.x/Use-Prolific.html +++ b/3.8.x/Use-Prolific.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Use Prolific

    It is very easy to use JATOS together with Prolific 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.

    Here is a screenshot of how it looks in Prolific:

    Prolific screenshot

    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).

    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

    And copy it into the End Redirect URL field of your Study Properties in JATOS:

    screenshot

    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.

    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 in the JavaScript of your last component

    E.g. but change this URL to the one you see in Prolific

    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    You can combine it with sending result data

    var resultData = {id: 123, data: "my important result data"};
    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    - +
    Skip to main content
    Version: 3.8.x

    Use Prolific

    It is very easy to use JATOS together with Prolific 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.

    Here is a screenshot of how it looks in Prolific:

    Prolific screenshot

    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).

    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

    And copy it into the End Redirect URL field of your Study Properties in JATOS:

    screenshot

    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.

    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 in the JavaScript of your last component

    E.g. but change this URL to the one you see in Prolific

    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    You can combine it with sending result data

    var resultData = {id: 123, data: "my important result data"};
    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    + \ No newline at end of file diff --git a/3.8.x/User-Manager.html b/3.8.x/User-Manager.html index 3b56afb8c..d895ac0de 100644 --- a/3.8.x/User-Manager.html +++ b/3.8.x/User-Manager.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Manage JATOS users

    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 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

    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

    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.

    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. 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). You can find more about how to configure JATOS to use 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. 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 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.

    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.

    - +
    Skip to main content
    Version: 3.8.x

    Manage JATOS users

    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 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

    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

    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.

    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. 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). You can find more about how to configure JATOS to use 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. 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 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.

    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/3.8.x/Whats-JATOS.html b/3.8.x/Whats-JATOS.html index 233c4f00c..82298d40d 100644 --- a/3.8.x/Whats-JATOS.html +++ b/3.8.x/Whats-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 150 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    - +
    Skip to main content
    Version: 3.8.x

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 150 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    + \ No newline at end of file diff --git a/3.8.x/Worker-Types.html b/3.8.x/Worker-Types.html index 577366d72..bef3fe3ca 100644 --- a/3.8.x/Worker-Types.html +++ b/3.8.x/Worker-Types.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Worker Types

    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.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Icon
    Typical useDuring study developmentSmall targeted group, each one of them gets a linkSmall targeted group of workers who pilot the study or need to do it multiple timesBigger groups but with less control; link shared e.g. via social mediaBigger groups and where the workers need to do it multiple timesFor Amazon Mechanical Turk
    Created when?Together with the JATOS userWhen you create the linkWhen you create the linkOn-the-fly whenever someone uses the linkOn-the-fly whenever someone uses the linkOn-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
    Possible bulk creation
    Run 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). 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

    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

    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). 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

    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 page for more details on this.

    - +
    Skip to main content
    Version: 3.8.x

    Worker Types

    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.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Icon
    Typical useDuring study developmentSmall targeted group, each one of them gets a linkSmall targeted group of workers who pilot the study or need to do it multiple timesBigger groups but with less control; link shared e.g. via social mediaBigger groups and where the workers need to do it multiple timesFor Amazon Mechanical Turk
    Created when?Together with the JATOS userWhen you create the linkWhen you create the linkOn-the-fly whenever someone uses the linkOn-the-fly whenever someone uses the linkOn-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
    Possible bulk creation
    Run 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). 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

    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

    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). 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

    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 page for more details on this.

    + \ No newline at end of file diff --git a/3.8.x/Write-Group-Studies-I-Setup.html b/3.8.x/Write-Group-Studies-I-Setup.html index 9c000ff28..4b0df87f2 100644 --- a/3.8.x/Write-Group-Studies-I-Setup.html +++ b/3.8.x/Write-Group-Studies-I-Setup.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study checkbox in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 (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

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 (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 (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    - +
    Skip to main content
    Version: 3.8.x

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study checkbox in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 (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

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 (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 (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    + \ No newline at end of file diff --git a/3.8.x/Write-Group-Studies-II-JavaScript-and-Messaging.html b/3.8.x/Write-Group-Studies-II-JavaScript-and-Messaging.html index af6b57906..ff17a00ba 100644 --- a/3.8.x/Write-Group-Studies-II-JavaScript-and-Messaging.html +++ b/3.8.x/Write-Group-Studies-II-JavaScript-and-Messaging.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.8.x

    Write Group Studies II - JavaScript and Messaging

    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:

    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 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.

    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.

    Reassigning to a different group​

    To move a worker from one group to a different one, use jatos.reassignGroup. 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 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. Alternatively you can fix a group in JATOS' GUI, in the -Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    - +Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    + \ No newline at end of file diff --git a/3.8.x/Write-your-own-Study-Basics-and-Beyond.html b/3.8.x/Write-your-own-Study-Basics-and-Beyond.html index 2d85021c7..31135a3f1 100644 --- a/3.8.x/Write-your-own-Study-Basics-and-Beyond.html +++ b/3.8.x/Write-your-own-Study-Basics-and-Beyond.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.8.x

    Write your own Study - Basics and Beyond

    After you created a new study ... what comes next?

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    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 and click on Components -> New.

    New Component

    Then in the following form you define the component's properties: enter 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

    Click on 'Create' and you are done. If you add more than one component you can change the order in which they run by drag-and-drop on the position button.

    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. The study assets directory's name is defined in your study properties.

    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>
        <head>
          <script src="jatos.js"></script>
        </head>
      </html>

    2. 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 untill jatos.js is finished initializing.

      <script>
        jatos.onLoad(function() {
          // Start here with your code that uses jatos.js' variables and functions
        });
      </script>

    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.

    jatos.js Reference​

    In your JavaScript you will use jatos.js to handle everything JATOS related and in its reference every function and field is described in detail.

    Study JSON Input and Component JSON 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 JSON Input or Component JSON Input because both can be easily edited in the Study Properties or Component Properties.

    Study Properties / JSON input

    Both input fields take JSON 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 JSON Input and Component JSON 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 JSON Input

    {
       "introduction": "this is a text",
       "order": [3, 1, 2]
    }

    you can access those fields in your JavaScript with jatos.studyJsonInput.introduction 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.

    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, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    - +To get an idea it's best to start with examples, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    + \ No newline at end of file diff --git a/3.8.x/jatos.js-Reference.html b/3.8.x/jatos.js-Reference.html index 94da718f3..1d91beecf 100644 --- a/3.8.x/jatos.js-Reference.html +++ b/3.8.x/jatos.js-Reference.html @@ -10,7 +10,7 @@ - + @@ -18,8 +18,8 @@
    Skip to main content
    Version: 3.8.x

    jatos.js Reference

    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 <head> section with the following line:

    <script src="jatos.js"></script>

    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.

    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

    jatos.groupResultId​

    see 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.

    2. 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).

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

      jatos.addAbortButton()

    2. Adds a cancel button and changes some properties

      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"
      });

    3. Adds a cancel button and changes the position to the bottom-left

      jatos.addAbortButton({
        style: "left:1em; right:unset"
      });

    4. Adds a cancel button and changes the position to the top-right

      jatos.addAbortButton({
        style: "top:1em; bottom:unset"
      });

    5. Adds a cancel button and calls 'myFunction' if pressed

      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:

    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.

      jatos.showOverlay()

    2. Shows text only

      jatos.showOverlay({
        text: "Please have a coffee break for 5 minutes",
        showImg: false
      });

    3. Shows text only

      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

    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:

    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

    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. This is useful in debugging.

    Example

    jatos.catchAndLogErrors();

    jatos.addJatosIds​

    Convenience function that adds some 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

    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

    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 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, 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

    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

    2. 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

      jatos.startComponent(23);

    2. Jump to component by using its UUID

      jatos.startComponent("3d277289-754b-4fd6-aa76-c8404deda02e");

    3. Send result data and jump to another component

      var resultData = "my important result data";
      jatos.startComponent(23, resultData);

    4. Send result data, jump to another component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startComponentByPos(3);

    2. Send result data and jump to component with position 3

      var resultData = "my important result data";
      jatos.startComponentByPos(3, resultData);

    3. Send result data, jump to component in position 3 and send a message back that will be visible in JATOS result pages and log

      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

    2. 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"

      jatos.startComponentByTitle("Some title");

    2. Send result data and jump to component with title "Some title"

      var resultData = "my important result data";
      jatos.startComponentByTitle("Some title", resultData);

    3. 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 

      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

    2. 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

      jatos.startNextComponent();

    2. Send result data and jump to the next component

      var resultData = "my important result data";
      jatos.startNextComponent(resultData);

    3. Send result data, jump to the next component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startLastComponent();

    2. Send result data and jump to the last component

      var resultData = "my important result data";
      jatos.startLastComponent(resultData);

    3. Send result data, jump to the last component and send a message back that will be visible in JATOS result pages and log

      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

      jatos.abortStudy();

    2. Additionally send a message

      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, 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

      jatos.abortStudyAjax();

    2. Abort study with a message that will be sent back to JATOS and shown in the result page and put in the log

      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

    2. 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

      jatos.endStudy();

    2. End study and send a message back that will be visible in JATOS result pages and log

      jatos.endStudy(true, "everything worked fine");

    3. Indicate a failure - leads to study result state FAIL

      jatos.endStudy(false, "internal JS error");

    4. Send result data and end study

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudy(resultData);

    5. Send result data, end study and send a message back that will be visible in JATOS result pages and log

      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, 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

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    2. End study and redirect afterwards. Send result data.

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);

    3. End study and redirect afterwards. A message will be sent back to JATOS and shown in the result page and put in the log.

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", true, "everything worked fine");

    4. End study and indicate a failure and send a message. Does not redirect.

      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, 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

      jatos.endStudyAjax();

    2. End study with a message that will be sent back to JATOS and shown in the result page and put in the log

      jatos.endStudyAjax(true, "everything worked fine");

    3. Indicate a failure and send a message

      jatos.endStudyAjax(false, "some error description");

    4. End study and show the confirmation code to the MTurk worker

      jatos.endStudyAjax().then((confirmationCode) => {
        // Show the confirmation code to the worker
      });

    5. Use Promise to submit result data and afterwards, end the study and move to another URL (see also)

      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"));

    6. Send result data and end study

      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, 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

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData);

    2. 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

      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)

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData, () => { jatos.startComponentByPos(4) });

    2. Or by using the returned Promise

      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, 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

      var resultData = { "a": 123, "b": 789, "c": 100 };
      jatos.appendResultData(resultData);

    2. Use mulitple jatos.appendResultData in a row

      jatos.appendResultData({"a": 1})
         .then(() => jatos.appendResultData({"b": 2}))
         .then(() => jatos.appendResultData({"c": 3}))
         .catch(() => console.log('Something went wrong'));

    3. You can use it together with jatos.startNextComponent to first append result data and afterwards jump to the next component

      var resultData = { "a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData, jatos.startNextComponent);

    4. Or by using the returned Promise

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData)
         .then(() => jatos.startNextComponent())
         .catch(() => console.log('Something went wrong'));

    5. Or together with jatos.startComponentByPos to start a particular component (here at position 4)

      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, to signal success or failure in the transfer.

    • @param {Blob, string or object} obj - Data to be uploaded as a file. Can be 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

      jatos.uploadResultFile("this is my data", "example.txt")
         .then(() => console.log("File was successfully uploaded"))
         .catch(() => console.log("File upload failed"));

    2. Upload object as JSON

      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"));

    3. Upload text as Blob

      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"));

    4. Turn canvas into Blob and upload as image file. It assumes you have an canvas element with ID 'canvas'.

      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"));
      });

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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 are returned as a Blob. It offers callbacks, either as parameter or via a 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

      jatos.downloadResultFile("example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    2. Download JSON file

      jatos.downloadResultFile("example.json")
         .then((obj) => console.log(JSON.stringify(obj)))
         .catch(() => console.log("File download failed"));

    3. Download image and display it in a canvas element

      jatos.downloadResultFile("canvas.png")
         .then((blob) => { document.getElementById("canvas").src = URL.createObjectURL(blob) })
         .catch(() => console.log("File download failed"));

    4. Download file and specify that the file was uploaded in the first component

      jatos.downloadResultFile(1, "example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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). 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.

    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) and JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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

      jatos.onBatchSession(function(path, op){
        console.log("Batch Session was updated in path " + path + " with operation " + op);
      });

    2. onBatchSession is often used together with jatos.batchSession.find to get the updated value:

      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"}

      // 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

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.batchSession.set("b", "koala")
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    3. Have a series of Batch Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

      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

    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).

    • @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"}}

      jatos.batchSession.test("/a", 123); // returns true
      jatos.batchSession.test("/a", 10); // returns false
      jatos.batchSession.test("/b/b1", "flowers"); // returns true

    2. 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.

      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). 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

      jatos.batchSession.add("/a", 100);

      After the Batch Session is successfully updated the new object is {"a": 100}.

    2. Add to Batch Session

      If the Batch Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or fail

      jatos.batchSession.add("/b", 123)
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    4. Add an object:

      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.

    5. Add an array:

      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]}.

    6. Add an element to an array:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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]}.

    7. Append to the end of an array using /-:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    8. Have a series of Batch Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    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, 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

      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));
      }

    2. Example that defines the onOpen, onMemberOpen, and onMessage callbacks

      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. 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

    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

      var msg = "Message for group member 1063";
      jatos.sendGroupMsgTo("1063", msg)

    2. Use the onMemberOpen callback to send a message right after a new member opened their group channel

      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, 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

    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, 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

    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, 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

    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

    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

    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

    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

    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

    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) and broadcast messaging (jatos.sendGroupMsg) (or: more general information about the different session types).

    In difference to 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). 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.

    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) and -JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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"}

      // 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.

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

    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

    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).

    • @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"}}

      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.

      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). 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

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    - +JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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.

    Examples

    1. Get a field from the Group Session

      Given the Group Session is {"a": 1000, "b": "watermelon"}

      // 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.

    2. 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"}}

      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.

    Examples

    1. Set a field in the Group Session

      If the Group Session is {"a": 1234}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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.

    Example

    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'.

    Examples

    1. Set the whole Group Session at once

      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.

    2. Use returned Promise to handle success or failure

      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 {}.

    Examples

    1. Clear the whole Group Session

      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.

    2. Use returned Promise to handle success or failure

      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.

    Example

    Given the Group Session is {"a": {"a1": "foo", "a2": "bar"}, "b": 999}

    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).

    Example

    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).

    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"}}

      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.

      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). 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.

    Examples

    1. Add an a field to the empty Group Session

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    Examples

    1. Remove a field from the Group Session

      If the Group Session is {"a": 100, "b": 123} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Replace a field in the Group Session

      If the Group Session is {"a": 100, "b": 123} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Copy a field in the Group Session from one location to another

      If the Group Session is {"a": "jatos"} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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).

    Examples

    1. Move a field in the Group Session from one location to another

      If the Group Session is {"a": "jatos"} and one calls

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    + \ No newline at end of file diff --git a/3.8.x/jsPsych-and-JATOS.html b/3.8.x/jsPsych-and-JATOS.html index 2494474c1..eedbb34c2 100644 --- a/3.8.x/jsPsych-and-JATOS.html +++ b/3.8.x/jsPsych-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. 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).

      var jsPsych = initJsPsych({
        on_trial_start: jatos.addAbortButton,
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad.

      jatos.onLoad(() => {
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    - +
    Skip to main content
    Version: 3.8.x

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. 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).

      var jsPsych = initJsPsych({
        on_trial_start: jatos.addAbortButton,
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad.

      jatos.onLoad(() => {
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    + \ No newline at end of file diff --git a/3.8.x/labjs-and-JATOS.html b/3.8.x/labjs-and-JATOS.html index e625d8e4d..fd2234444 100644 --- a/3.8.x/labjs-and-JATOS.html +++ b/3.8.x/labjs-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.8.x

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their Builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    - +
    Skip to main content
    Version: 3.8.x

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their Builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    + \ No newline at end of file diff --git a/404.html b/404.html index 803115549..51ef7d8d0 100644 --- a/404.html +++ b/404.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    Page Not Found

    We could not find what you were looking for.

    Please contact the owner of the site that linked you to the original URL and let them know their link is broken.

    - + \ No newline at end of file diff --git a/Adapt-pre-written-code-to-run-it-in-JATOS.html b/Adapt-pre-written-code-to-run-it-in-JATOS.html index f4b77213c..8737a4c87 100644 --- a/Adapt-pre-written-code-to-run-it-in-JATOS.html +++ b/Adapt-pre-written-code-to-run-it-in-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Adapt pre written code to run it in JATOS

    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

    Add the study in your local JATOS​

    1. Add 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/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. Back in the JATOS GUI, and within the newly added study, add 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.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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.

    5. 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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, component input, or batch input, defined in the study/component/batch 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.
    - +
    Skip to main content
    Version: 3.9.x

    Adapt pre written code to run it in JATOS

    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

    Add the study in your local JATOS​

    1. Add 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/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. Back in the JATOS GUI, and within the newly added study, add 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.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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.

    5. 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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, component input, or batch input, defined in the study/component/batch 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.
    + \ No newline at end of file diff --git a/Administration.html b/Administration.html index d04226e97..17117044d 100644 --- a/Administration.html +++ b/Administration.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    Study Manager​

    By clicking the Study Manager 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

    Study Manager

    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 switch 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.
    • ID - The study ID
    • Title - The study title
    • Members - The users who are members of this study
    • 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.
    - +
    Skip to main content
    Version: 3.9.x

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    Study Manager​

    By clicking the Study Manager 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

    Study Manager

    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 switch 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.
    • ID - The study ID
    • Title - The study title
    • Members - The users who are members of this study
    • 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.
    + \ No newline at end of file diff --git a/Bring-your-JATOS-online.html b/Bring-your-JATOS-online.html index e05e86886..39e1f8c4d 100644 --- a/Bring-your-JATOS-online.html +++ b/Bring-your-JATOS-online.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    Bring your JATOS online

    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 timeSetup difficultyCostNumber of JATOS user / JATOS workers
    1. Expose your local JATOSfasteasynoneyou / few †
    2. Cloud serverfast to mediumdepends on your vendoryesmany / many ‡
    3. Own servermedium to slow (depends on your IT)needs admin skillsask your ITmany / many ‡

    †) 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

    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 or JATOS on AWS (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

    - +‡) 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

    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 or JATOS on AWS (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

    + \ No newline at end of file diff --git a/Change-studys-members.html b/Change-studys-members.html index b704c57a3..683399726 100644 --- a/Change-studys-members.html +++ b/Change-studys-members.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Change study's members

    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&#39;s members button

    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 clicking the Remove button in the user's row.

    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&#39;s members

    - +
    Skip to main content
    Version: 3.9.x

    Change study's members

    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&#39;s members button

    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 clicking the Remove button in the user's row.

    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&#39;s members

    + \ No newline at end of file diff --git a/Combine-two-pre-written-studies-into-one.html b/Combine-two-pre-written-studies-into-one.html index 347c0f5ea..6deab4abc 100644 --- a/Combine-two-pre-written-studies-into-one.html +++ b/Combine-two-pre-written-studies-into-one.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Combine two pre-written studies into one

    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 and a perceptual experiment with OSWeb. 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 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.
    2. Information about where your study assets are: Go to 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.
    3. The .jzip for the first half of your study.
    4. 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 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. study input or component 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:

    jatos.startNextComponent(myResultDataObject);

    and not 

    jatos.endStudy(myResultDataObject);
    - +
    Skip to main content
    Version: 3.9.x

    Combine two pre-written studies into one

    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 and a perceptual experiment with OSWeb. 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 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.
    2. Information about where your study assets are: Go to 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.
    3. The .jzip for the first half of your study.
    4. 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 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. study input or component 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:

    jatos.startNextComponent(myResultDataObject);

    and not 

    jatos.endStudy(myResultDataObject);
    + \ No newline at end of file diff --git a/Connect-to-Mechanical-Turk.html b/Connect-to-Mechanical-Turk.html index 9d32b5288..30baa1777 100644 --- a/Connect-to-Mechanical-Turk.html +++ b/Connect-to-Mechanical-Turk.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    - +
    Skip to main content
    Version: 3.9.x

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    + \ No newline at end of file diff --git a/Contact-us.html b/Contact-us.html index 08e920e19..68bbb42fd 100644 --- a/Contact-us.html +++ b/Contact-us.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    - +
    Skip to main content
    Version: 3.9.x

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    + \ No newline at end of file diff --git a/Create-a-new-study.html b/Create-a-new-study.html index 4678108ca..6cf0c836c 100644 --- a/Create-a-new-study.html +++ b/Create-a-new-study.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Create a new study

    There are different ways to add 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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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) 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.

    - +
    Skip to main content
    Version: 3.9.x

    Create a new study

    There are different ways to add 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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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) 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.

    + \ No newline at end of file diff --git a/Cross-sectional-and-longitudinal-studies.html b/Cross-sectional-and-longitudinal-studies.html index 298697db2..fd75c37ef 100644 --- a/Cross-sectional-and-longitudinal-studies.html +++ b/Cross-sectional-and-longitudinal-studies.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    - +
    Skip to main content
    Version: 3.9.x

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    + \ No newline at end of file diff --git a/Customize-JATOS-Home-Page.html b/Customize-JATOS-Home-Page.html index 24d4172be..17928e98a 100644 --- a/Customize-JATOS-Home-Page.html +++ b/Customize-JATOS-Home-Page.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Customize JATOS' Home Page

    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.

    template customized home page

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    - +
    Skip to main content
    Version: 3.9.x

    Customize JATOS' Home Page

    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.

    template customized home page

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    + \ No newline at end of file diff --git a/Data-Privacy-and-Ethics.html b/Data-Privacy-and-Ethics.html index af1b872cb..f57aee200 100644 --- a/Data-Privacy-and-Ethics.html +++ b/Data-Privacy-and-Ethics.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Data privacy and ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    - +
    Skip to main content
    Version: 3.9.x

    Data privacy and ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    + \ No newline at end of file diff --git a/Deploy-to-a-server-installation.html b/Deploy-to-a-server-installation.html index 9fa558826..5c0cb6882 100644 --- a/Deploy-to-a-server-installation.html +++ b/Deploy-to-a-server-installation.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Deploy to a server installation

    Usually you conveniently develop your study on your local computer where you have a local installation of JATOS. Then just use the export and import buttons in your installations to transfer the study to your JATOS server.

    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 file wherever you like on your computer.
    2. 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. 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.
    - +
    Skip to main content
    Version: 3.9.x

    Deploy to a server installation

    Usually you conveniently develop your study on your local computer where you have a local installation of JATOS. Then just use the export and import buttons in your installations to transfer the study to your JATOS server.

    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 file wherever you like on your computer.
    2. 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. 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.
    + \ No newline at end of file diff --git a/End-page-after-your-study-finished.html b/End-page-after-your-study-finished.html index 27a8793fb..dd075d398 100644 --- a/End-page-after-your-study-finished.html +++ b/End-page-after-your-study-finished.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    End page - After your study finished

    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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    - +
    Skip to main content
    Version: 3.9.x

    End page - After your study finished

    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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    + \ No newline at end of file diff --git a/Example-Group-Studies.html b/Example-Group-Studies.html index 8f3205895..d6193c541 100644 --- a/Example-Group-Studies.html +++ b/Example-Group-Studies.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    - +
    Skip to main content
    Version: 3.9.x

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    + \ No newline at end of file diff --git a/Example-Studies.html b/Example-Studies.html index 8c797d8f8..9e6ea7149 100644 --- a/Example-Studies.html +++ b/Example-Studies.html @@ -10,13 +10,13 @@ - +
    Skip to main content

    Example Studies

    summary: These study examples will (hopefully) be a helpful starting point for you to write your own studies. They also show how different client-side frameworks integrate with JATOS, and illustrate (e.g.) how to easily import/export studies, how to store and show results, and how to do messaging in group studies.

    Overview​

    JATOS gives you complete freedom on the client side. You can do whatever you like! You can use in your study code whatever technologies work in browsers (e.g. HTML5 canvas, CSS3 or 3D graphics with WebGL). Additionally browser-side JavaScript libraries or frameworks like Bootstrap, Highcharts, p5, or jsPsych are possible and will smooth out your path to quick and easy development. Of course the same is true for CSS modules (e.g. Pure.css, Material Design). These are some examples of how to use these client-side frameworks in combination with JATOS.

    Click on the study name to download the .jzip file and import it into JATOS.

    If you have trouble downloading a study (common in Safari browsers) check this troubleshooting tip.

    If you wrote an example study that you'd like to share, please feel free to contact us and we'll include it in this page!

    Example studies​

    Study NameBrief DescriptionFrameworks UsedJATOS FeaturesExample Image
    Hello WorldEverything starts with a Hello World!---
    Simple Reaction Time Task †Go/NoGo task. Includes instructionsjsPsych 7-
    Randomize Tasks Between Workers §Template to randomly assign participants to conditions A, B, or C (with fixed numbers for each condition).-Batch session
    Lexical DecisionParticipants classify whether a string of letters is a word or a nonword. From factorsdb.jsPsych-
    Lexical Decision ∗An example of running OpenSesame experiments with JATOS via OSWeb.OpenSesame, OSWeb-
    Random Dot Kinematogram ∗A random dot kinematogram (RDK) for online visual psychophysics and the use in web browsers. By Sivananda Rajananda, Hakwan Lau, Brian Odegaard (preprint).jsPsych-
    Demographic and Survey Questions ∗SurveyJS is an easy to use library with a great online interface to create surveys and questionaires.SurveyJS-
    Instructions with Google Slides ∗Use Google Slides to make an quick, easy and versatile instruction page. Might not be the prettiest, but it does the job.Google Slides-
    p5.js 2D Graphics Showcase ∗p5.js is a graphics library to easily create 2D and 3D graphics without deeper knowledge of how those graphics are rendered. Additionally one can add user interaction, video, sound, or capture from the webcam or the mic. Have a look at their example section.p5.js-
    VideoShows how to embed a video with HTML 5 by using the browsers video player, YouTube, or the video.js JavaScript library.--
    Results in CSVSimple example of how to store results in CSV format.--
    Simple Consent FormSimple example of a consent form with text and buttons ‘I agree’ and ‘Cancel’.--
    Introduction and Consent with Preview FeatureThis mobile-friendly example just has an introduction component that includes a consent text.-Preview links
    Prolific Example §Example on how to redirect in the end of the study back to Prolific--
    2048 GameThis addictive game is created by Gabriele Cirulli.--
    Plot DataA slightly different use for JATOS: as a regular server to display an HTML page that displays study results.Highcharts-
    Attentional Capture ∗Standard task to show how to use OSWeb with JATOS.OpenSesame, OSWeb-
    Survey (Self Regulation)A standard questionnaire. Taken from expfactory.JQuery Form-
    Invaders GameClassical arcade game. From Phaser's examples page.phaser.io-
    HexGL Game ∗Futuristic racing game by Thibaut Despoulain.HTML5, WebGL-
    Mouse Tracking with Arithmetics §Following Pinheiro-Chagas, P., Dotan, D., Piazza, M., & Dehaene, S. (2017). Finger tracking reveals the covert stages of mental arithmetic. Open Mind: Discoveries in Cognitive Science, 1(1), 30–41. doi:10.1162/opmia00003--
    Binocular Rivalry §Using Gabor patches to demonstrate binocular rivalry with a Google Cardboard--
    Bistable Perception §---
    Change Blindness §---
    Dot Densitity Metacognition §---
    Deary-Liewald task with PsyToolkit §Taken from PsyToolkit's experiment libraryPsyToolkit-
    Clock Drawing §Submit images as result data to JATOS by converting them into base64-encoded text.jsPsych-
    Potato CompassDrag & drop elements.interact.js-
    Audio Recording †Record audio and upload as a file to JATOS. Bases on web-dictaphone and uses getUserMedia and MediaRecorder API for recording audio snippets, and The Web Audio API for visualizations.--
    Video Recording †Record a video with the webcam and upload the data as a file to JATOS--
    Drawing †Simple drawing app that lets you upload the image to JATOS--
    Browser Information and Worker Tracking §Gets information about the participants browser, computer and location--
    Study, Group, and Batch Session §See JATOS’ three different session types in action.-Study, Group, and Batch session data
    Group Chat ∗Let members of a group talk to each other.-Group Session, Group Broadcast Message
    Batch Chat ∗Let members of a batch talk to each other.-Batch Session
    Chat with Markdown and Emojis §Chat that builds on top of Batch Chat and adds suports for Markdown and emojis--
    Prisoner's Dilemma §Game in which two workers interact with each other in the same study run.-Group Study, Group Direct Messaging
    Snake Game ∗Multiplayer real-time snake game.-Group Study, Group Broadcast Message

    ∗ Requires JATOS version 3.1.1 or newer

    § Requires JATOS version 3.3.1 or newer

    † Requires JATOS version 3.5.1 or newer

    Example studies contributed by others​

    Study NameBrief DescriptionFrameworks UsedJATOS FeaturesContributed ByExample Image
    Randomize (Multi-component) Tasks Between Workers §Template to randomly assign participants to conditions A or B, where each condition is composed of two different components. This is an extension of the "Randomize Tasks Between Workers' example above-Batch sessionCraig Stark, Ph.D., School of Biological Sciences, University of California, Irvin
    - + \ No newline at end of file diff --git a/Expose-your-local-JATOS.html b/Expose-your-local-JATOS.html index 63347da17..b35d3a303 100644 --- a/Expose-your-local-JATOS.html +++ b/Expose-your-local-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can add study links and send them to your participants. Remember to use JATOS under the ngrog.io address when you add study links (and not your localhost one).

    More information on https://ngrok.com.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can add study links and send them to your participants. Remember to use JATOS under the localhost.run address when you add study links (and not your localhost one).

    More information on http://localhost.run/.

    - +
    Skip to main content
    Version: 3.9.x

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can add study links and send them to your participants. Remember to use JATOS under the ngrog.io address when you add study links (and not your localhost one).

    More information on https://ngrok.com.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can add study links and send them to your participants. Remember to use JATOS under the localhost.run address when you add study links (and not your localhost one).

    More information on http://localhost.run/.

    + \ No newline at end of file diff --git a/Get-started.html b/Get-started.html index 8915a8fce..c23bda1c4 100644 --- a/Get-started.html +++ b/Get-started.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    Get started

    Get started in 4 steps​

    1. Download JATOS and install a local instance

    2. Open JATOS' GUI by going to localhost:9000 in your browser window

    3. Download and import an example study

      1. Download one of the Example Studies, e.g. the 'Go- / No-Go Task' with jsPsych. Do not unzip the downloaded file.

      2. Import the study into JATOS: Go to JATOS' GUI in your browser and click on Import Study in the header. Choose the .jzip file you just downloaded. The imported study should appear in the sidebar on the left.

    4. 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).

      Here's a screenshot of a study's results view: -Results View screenshot

    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/.
    - +Results View screenshot

    Explore​

    Now it's time to explore a little bit more.

    + \ No newline at end of file diff --git a/Install-JATOS-via-Docker.html b/Install-JATOS-via-Docker.html index d64f3e814..f3b6278cc 100644 --- a/Install-JATOS-via-Docker.html +++ b/Install-JATOS-via-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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 for some advanced Docker setup.

    Installation with Docker​

    1. In your terminal:

      • Get the latest release:
      docker pull jatos/jatos:latest
      • or a specific release (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    2. Run JATOS (change latest to your version)

      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.

    3. 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 - it should show the JATOS login screen
      • Check JATOS' administration page: 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

    4. Always change the admin's password after first installation: Go to 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:

    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:

    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 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):

    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 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):

    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 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:

    docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest

    Persist data with volumes​

    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:

    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:

    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, you can simply use the auto-update feature to update JATOS to newer versions.

    2. 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 - If you don't use volumes your data stored in JATOS will be lost.

    - +
    Skip to main content
    Version: 3.9.x

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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 for some advanced Docker setup.

    Installation with Docker​

    1. In your terminal:

      • Get the latest release:
      docker pull jatos/jatos:latest
      • or a specific release (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    2. Run JATOS (change latest to your version)

      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.

    3. 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 - it should show the JATOS login screen
      • Check JATOS' administration page: 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

    4. Always change the admin's password after first installation: Go to 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:

    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:

    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 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):

    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 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):

    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 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:

    docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest

    Persist data with volumes​

    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:

    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:

    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, you can simply use the auto-update feature to update JATOS to newer versions.

    2. 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 - If you don't use volumes your data stored in JATOS will be lost.

    + \ No newline at end of file diff --git a/Installation.html b/Installation.html index 554140516..440840f0e 100644 --- a/Installation.html +++ b/Installation.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    Installation

    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 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) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
      • Without Java: jatos.zip
      • Bundled with Java: jatos_win_java.zip
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
      • Without Java: jatos.zip
      • For MacOS bundled with Java: jatos_mac_java.zip
      • For Linux bundled with Java: jatos_linux_java.zip
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. (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.)
    6. All set! Now go to the browser of your choice and open 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 and play around with it.

    - +If you don't have Java installed, you can either download and install it (e.g. from adoptium.net) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. (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.)
    6. All set! Now go to the browser of your choice and open 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 and play around with it.

    + \ No newline at end of file diff --git a/JATOS-API.html b/JATOS-API.html index c39731a7c..110b548d0 100644 --- a/JATOS-API.html +++ b/JATOS-API.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS API

    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 in your local JATOS. (The JATOS API uses personal access tokens with bearer authentication.)
    2. Copy your token
    3. Go to petstore.swagger.io. You'll see all API endpoints and their descriptions.
    4. 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.
    5. Choose the server http://localhost:9000 (probably already set)
    6. 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. You can use petstore.swagger.io 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.

    Authentication​

    The JATOS API uses bearer authentication. It's pretty simple.

    From swagger.io:

    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 <token> with your token):

    Authorization: Bearer <token>

    And an example in different tools/languages with the endpoint /jatos/api/v1/admin/token that just returns some info about the used token:

    curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token

    Personal access tokens​

    The JATOS API uses personal access tokens (PATs or API tokens).

    From wikipedia:

    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 added, 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

    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

    Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

    API token 1

    In the token overview windows you can temporarily deactivate a token or delete it altogether.

    API token 1

    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:

    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'

    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
    - +
    Skip to main content
    Version: 3.9.x

    JATOS API

    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 in your local JATOS. (The JATOS API uses personal access tokens with bearer authentication.)
    2. Copy your token
    3. Go to petstore.swagger.io. You'll see all API endpoints and their descriptions.
    4. 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.
    5. Choose the server http://localhost:9000 (probably already set)
    6. 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. You can use petstore.swagger.io 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.

    Authentication​

    The JATOS API uses bearer authentication. It's pretty simple.

    From swagger.io:

    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 <token> with your token):

    Authorization: Bearer <token>

    And an example in different tools/languages with the endpoint /jatos/api/v1/admin/token that just returns some info about the used token:

    curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token

    Personal access tokens​

    The JATOS API uses personal access tokens (PATs or API tokens).

    From wikipedia:

    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 added, 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

    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

    Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

    API token 1

    In the token overview windows you can temporarily deactivate a token or delete it altogether.

    API token 1

    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:

    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'

    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
    + \ No newline at end of file diff --git a/JATOS-Results-Archive-JRZIP.html b/JATOS-Results-Archive-JRZIP.html index dcff7aa91..460a8690a 100644 --- a/JATOS-Results-Archive-JRZIP.html +++ b/JATOS-Results-Archive-JRZIP.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS Results Archive (JRZIP)

    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​

    {
        "$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"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    - +
    Skip to main content
    Version: 3.9.x

    JATOS Results Archive (JRZIP)

    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​

    {
        "$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"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    + \ No newline at end of file diff --git a/JATOS-Study-Archive-JZIP.html b/JATOS-Study-Archive-JZIP.html index ab66540b0..921eaecd6 100644 --- a/JATOS-Study-Archive-JZIP.html +++ b/JATOS-Study-Archive-JZIP.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS Study Archive (JZIP)

    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​

    {
        "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​

    {
        "$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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    - +
    Skip to main content
    Version: 3.9.x

    JATOS Study Archive (JZIP)

    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​

    {
        "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​

    {
        "$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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    + \ No newline at end of file diff --git a/JATOS-Tryout-Server.html b/JATOS-Tryout-Server.html index 860d978fe..bf9df3e47 100644 --- a/JATOS-Tryout-Server.html +++ b/JATOS-Tryout-Server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS tryout server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    - +
    Skip to main content
    Version: 3.9.x

    JATOS tryout server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    + \ No newline at end of file diff --git a/JATOS-in-Amazons-Cloud-without-Docker.html b/JATOS-in-Amazons-Cloud-without-Docker.html index 95a4a1cb6..80ea3f8f8 100644 --- a/JATOS-in-Amazons-Cloud-without-Docker.html +++ b/JATOS-in-Amazons-Cloud-without-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache 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
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    - +
    Skip to main content
    Version: 3.9.x

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache 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
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    + \ No newline at end of file diff --git a/JATOS-in-a-cluster.html b/JATOS-in-a-cluster.html index 96f2434d8..d22c52840 100644 --- a/JATOS-in-a-cluster.html +++ b/JATOS-in-a-cluster.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS in a cluster

    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 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. 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 additionally (if you haven't already):

    1. Set -Djatos.multiNode=true in the command section of the jatos service.
    2. 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:

    docker compose -f compose.yaml up --scale jatos=2

    JATOS with Kubernetes​

    Kubernetes 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 - but with some adjustments it should work on any Kubernetes cluster.

    For the JATOS cluster we use Kustomize to define Kubernetes objects through kustomization YAML files.

    We assembled all necessary files in a git repository.

    git clone https://github.com/JATOS/JATOS_with_kubernetes.git

    The file kustomization.yaml defines our secrets and specifies the resource file, jatos.yaml, that describes the JATOS cluster.

    Then, after you set up everything, you can start the cluster with:

    kubectl apply -k <my_JATOS_kustomize_directory>

    Load-balancing and scaling​

    In our jatos.yaml, for auto-balancing in our JATOS cluster, we use the one integrated in DigitalOcean. This is specified in the Service object, with the annotation kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer".

    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%. 

    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, 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 for this purpose: nfs-server-provisioner. And since we want to run on DigitalOcean we need the parameter persistence.storageClass set to do-block-storage.

    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 the NFS storage is used in a PersistentVolumeClaim:

    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:

    volumes:
      - name: jatos-data-storage
        persistentVolumeClaim:
          claimName: jatos-data-pv-claim

    Configure JATOS' deployment​

    In 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.

    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 file and then just referenced in 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 to get started.

    In 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, a startupProbe that accounts for this. You might have to tweak failureThreshold and periodSeconds on your system.

    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 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. 

    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.

    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 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.
    2. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation.
    3. And please do backups before updating.
    - +
    Skip to main content
    Version: 3.9.x

    JATOS in a cluster

    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 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. 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 additionally (if you haven't already):

    1. Set -Djatos.multiNode=true in the command section of the jatos service.
    2. 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:

    docker compose -f compose.yaml up --scale jatos=2

    JATOS with Kubernetes​

    Kubernetes 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 - but with some adjustments it should work on any Kubernetes cluster.

    For the JATOS cluster we use Kustomize to define Kubernetes objects through kustomization YAML files.

    We assembled all necessary files in a git repository.

    git clone https://github.com/JATOS/JATOS_with_kubernetes.git

    The file kustomization.yaml defines our secrets and specifies the resource file, jatos.yaml, that describes the JATOS cluster.

    Then, after you set up everything, you can start the cluster with:

    kubectl apply -k <my_JATOS_kustomize_directory>

    Load-balancing and scaling​

    In our jatos.yaml, for auto-balancing in our JATOS cluster, we use the one integrated in DigitalOcean. This is specified in the Service object, with the annotation kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer".

    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%. 

    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, 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 for this purpose: nfs-server-provisioner. And since we want to run on DigitalOcean we need the parameter persistence.storageClass set to do-block-storage.

    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 the NFS storage is used in a PersistentVolumeClaim:

    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:

    volumes:
      - name: jatos-data-storage
        persistentVolumeClaim:
          claimName: jatos-data-pv-claim

    Configure JATOS' deployment​

    In 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.

    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 file and then just referenced in 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 to get started.

    In 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, a startupProbe that accounts for this. You might have to tweak failureThreshold and periodSeconds on your system.

    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 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. 

    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.

    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 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.
    2. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation.
    3. And please do backups before updating.
    + \ No newline at end of file diff --git a/JATOS-on-DigitalOcean.html b/JATOS-on-DigitalOcean.html index 51d727a7b..a27ad0467 100644 --- a/JATOS-on-DigitalOcean.html +++ b/JATOS-on-DigitalOcean.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS on DigitalOcean

    Here we explain how to install JATOS in the cloud by using DigitalOcean. 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.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Create a Droplet (this is what DigitalOcean calls a virtual machine that we want to use as a server).

    3. Choose the Region that is nearest to your users.

    4. Choose an image from Marketplace: select one with Docker on Ubuntu pre-installed.

    5. 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.

    6. Choose an authentication method

    7. Click on Advanced Options and activate Add Initialization scripts. Then copy+paste the following script in the text field:

      #!/bin/bash
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      You can change 'latest' to the specific version you need.

    8. Finally click the Create Droplet button

    9. 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.

    10. 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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source 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
    2. Set up your DNS
    3. Restart droplet
    4. 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) but in the field for the Add Initialization scripts put the following script:

    #!/bin/bash

    # Change to your email and domain (for Let's Encrypt)
    email=myemail@example.org
    domain=my.domain.org

    cat >/root/compose.yaml <<EOL
    version: "3.8"

    services:

      traefik:
        image: "traefik:v2.10"
        container_name: "traefik"
        command:
          #- "--log.level=DEBUG"
          - "--api.insecure=true"
          - "--providers.docker=true"
          - "--providers.docker.exposedbydefault=false"
          - "--entrypoints.web.address=:80"
          - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
          - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
          - "--entrypoints.websecure.address=:443"
          - "--certificatesresolvers.jatosresolver.acme.tlschallenge=true"
          #- "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
          - "--certificatesresolvers.jatosresolver.acme.email=${email}"
          - "--certificatesresolvers.jatosresolver.acme.storage=/letsencrypt/acme.json"
        ports:
          - "80:80"
          - "443:443"
        volumes:
          - "./letsencrypt:/letsencrypt"
          - "/var/run/docker.sock:/var/run/docker.sock:ro"

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        ports:
          - "9000:9000"
        volumes:
          - "jatos-logs:/opt/jatos/logs"
          - "jatos-data:/opt/jatos_data"
        labels:
          - "traefik.enable=true"
          - "traefik.http.routers.jatos.rule=Host(\`${domain}\`)"
          - "traefik.http.services.jatos.loadbalancer.server.port=9000"
          - "traefik.http.routers.jatos.entrypoints=websecure"
          - "traefik.http.routers.jatos.tls.certresolver=jatosresolver"

    volumes:
      jatos-data:
      jatos-logs:
    EOL

    docker compose -f /root/compose.yaml up -d

    This script will use Docker Compose to set up Traefik and JATOS. It creates a Docker Compose config file under /root/compose.yaml and then runs it with docker compose up.

    Before you can click the Create Droplet button, change my.domain.org and myemail@example.org (in the top of the script) with your own domain name and email address. Your email is needed to get a certificate from Let's Encrypt for encryption. Also, you might want to set JATOS version to a specific release: change latest in the line image: "jatos/jatos:latest".

    Set up your DNS​

    After you've created your Droplet, you still have to point your domain name to your server's IP address. This is what a DNS (Domain Name Service) does and it involves dealing with things like DNS records, especially A records or AAAA records, and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registrar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Restart​

    Then as a last step, after your domain name points to your server's IP, you have to restart your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and uses HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption and your domain name.

    Misc​

    • Let's Encrypt has a rate limit for the number of certificates. If you are not sure and just want to try it out, uncomment the following line in the Initialization script:

      - "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

      This will let you use their staging server that does not have such rate limit - but you won't get a proper certificate either.

    • The Docker Compose config file that is created during the Droplet initialization has the path /root/compose.yaml and the certificate is stored under /root/letsencrypt/.

    • You can configure JATOS by changing the /root/compose.yaml. You can add all command-line arguments of JATOS in the command section of the jatos service_.

      E.g. to add a welcome message on the home page use -Djatos.brandingUrl:

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.brandingUrl=https://mydomain.com/foobar-university-welcome-page.html'
          ...

      E.g. to let JATOS use an external MySQL database use -Djatos.db.url, -Djatos.db.username, -Djatos.db.password, and -Djatos.db.driver (change IP, port, username and password to the ones of your database)

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.db.url=jdbc:mysql://1.2.3.4: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'
          ...
    - +
    Skip to main content
    Version: 3.9.x

    JATOS on DigitalOcean

    Here we explain how to install JATOS in the cloud by using DigitalOcean. 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.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Create a Droplet (this is what DigitalOcean calls a virtual machine that we want to use as a server).

    3. Choose the Region that is nearest to your users.

    4. Choose an image from Marketplace: select one with Docker on Ubuntu pre-installed.

    5. 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.

    6. Choose an authentication method

    7. Click on Advanced Options and activate Add Initialization scripts. Then copy+paste the following script in the text field:

      #!/bin/bash
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      You can change 'latest' to the specific version you need.

    8. Finally click the Create Droplet button

    9. 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.

    10. 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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source 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
    2. Set up your DNS
    3. Restart droplet
    4. 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) but in the field for the Add Initialization scripts put the following script:

    #!/bin/bash

    # Change to your email and domain (for Let's Encrypt)
    email=myemail@example.org
    domain=my.domain.org

    cat >/root/compose.yaml <<EOL
    version: "3.8"

    services:

      traefik:
        image: "traefik:v2.10"
        container_name: "traefik"
        command:
          #- "--log.level=DEBUG"
          - "--api.insecure=true"
          - "--providers.docker=true"
          - "--providers.docker.exposedbydefault=false"
          - "--entrypoints.web.address=:80"
          - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
          - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
          - "--entrypoints.websecure.address=:443"
          - "--certificatesresolvers.jatosresolver.acme.tlschallenge=true"
          #- "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
          - "--certificatesresolvers.jatosresolver.acme.email=${email}"
          - "--certificatesresolvers.jatosresolver.acme.storage=/letsencrypt/acme.json"
        ports:
          - "80:80"
          - "443:443"
        volumes:
          - "./letsencrypt:/letsencrypt"
          - "/var/run/docker.sock:/var/run/docker.sock:ro"

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        ports:
          - "9000:9000"
        volumes:
          - "jatos-logs:/opt/jatos/logs"
          - "jatos-data:/opt/jatos_data"
        labels:
          - "traefik.enable=true"
          - "traefik.http.routers.jatos.rule=Host(\`${domain}\`)"
          - "traefik.http.services.jatos.loadbalancer.server.port=9000"
          - "traefik.http.routers.jatos.entrypoints=websecure"
          - "traefik.http.routers.jatos.tls.certresolver=jatosresolver"

    volumes:
      jatos-data:
      jatos-logs:
    EOL

    docker compose -f /root/compose.yaml up -d

    This script will use Docker Compose to set up Traefik and JATOS. It creates a Docker Compose config file under /root/compose.yaml and then runs it with docker compose up.

    Before you can click the Create Droplet button, change my.domain.org and myemail@example.org (in the top of the script) with your own domain name and email address. Your email is needed to get a certificate from Let's Encrypt for encryption. Also, you might want to set JATOS version to a specific release: change latest in the line image: "jatos/jatos:latest".

    Set up your DNS​

    After you've created your Droplet, you still have to point your domain name to your server's IP address. This is what a DNS (Domain Name Service) does and it involves dealing with things like DNS records, especially A records or AAAA records, and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registrar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Restart​

    Then as a last step, after your domain name points to your server's IP, you have to restart your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and uses HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption and your domain name.

    Misc​

    • Let's Encrypt has a rate limit for the number of certificates. If you are not sure and just want to try it out, uncomment the following line in the Initialization script:

      - "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

      This will let you use their staging server that does not have such rate limit - but you won't get a proper certificate either.

    • The Docker Compose config file that is created during the Droplet initialization has the path /root/compose.yaml and the certificate is stored under /root/letsencrypt/.

    • You can configure JATOS by changing the /root/compose.yaml. You can add all command-line arguments of JATOS in the command section of the jatos service_.

      E.g. to add a welcome message on the home page use -Djatos.brandingUrl:

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.brandingUrl=https://mydomain.com/foobar-university-welcome-page.html'
          ...

      E.g. to let JATOS use an external MySQL database use -Djatos.db.url, -Djatos.db.username, -Djatos.db.password, and -Djatos.db.driver (change IP, port, username and password to the ones of your database)

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.db.url=jdbc:mysql://1.2.3.4: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'
          ...
    + \ No newline at end of file diff --git a/JATOS-on-a-server.html b/JATOS-on-a-server.html index 4164990d2..e36d189cb 100644 --- a/JATOS-on-a-server.html +++ b/JATOS-on-a-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    And there are dedicated pages for installation with Docker and Docker Compose.

    Installing JATOS as a Internet server usually involves exchanging the embedded database with a MySQL/MariaDB one and setting up a reverse proxy (mostly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.

    Install Java​

    JATOS needs Java 11 to run (higher versions are not yet supported). You can install your own Java or get a JATOS that is already bundled with Java.

    Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Run JATOS:

      ./loader.sh start

      And to stop it:

      Usually Ctr+C does the job, but if your JATOS runs in the background:

      ./loader.sh stop

    5. Check JATOS is running correctly:

      Use curl: curl http://localhost:9000/ping should give you pong back

      If you can already access your server from the outside, open JATOS in a browser (the default port is 9000): http://my-IP-or-domain:9000. It should show the JATOS login screen. You can log in with username admin and password admin.

      Check JATOS' Administration page: http://my-IP-or-domain/jatos/admin. Click the Tests button: all tests should show an 'OK'. Click on System Info and check that all is like you configured it.

    6. Always change admin's password

      This can be done in JATOS' GUI:

      1. In a browser go to JATOS' login page http://my-IP-or-domain/jatos
      2. Log in as 'admin' with password 'admin'
      3. Click on Admin (admin) in top-right header
      4. Click Change Password

    [Optional] Install MySQL/MariaDB​

    See JATOS with MySQL

    Configuration​

    These docs have an extra page on JATOS Configuration. E.g. you can add user authentication with ORCID (orcid.org), OpenID Connect (OIDC), LDAP, or Google Sign-in.

    [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    [Optional] Specify the location of JATOS' data folders​

    By default all data folders are located in JATOS installation folder. But sometimes it is better to change the location to better suit your needs, e.g. for easier backups or updates.

    JATOS' data folders (and their path configuration):

    One might want to move all data folders in one extra 'data' folder. E.g. in JATOS' config file the following properties have to be set:

    jatos.studyAssetsRootPath = "/path/to/my/jatos-data-folder/study_assets_root"
    jatos.resultUploads.path =  "/path/to/my/jatos-data-folder/result_uploads"
    jatos.studyLogs.path =      "/path/to/my/jatos-data-folder/study_logs"

    Or with command-line arguments this would be:

    -Djatos.studyAssetsRootPath="/path/to/my/jatos-data-folder/study_assets_root" -Djatos.resultUploads.path="/path/to/my/jatos-data-folder/result_uploads" -Djatos.studyLogs.path="/path/to/my/jatos-data-folder/study_logs"

    [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularly.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the data folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to stop JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    1. JATOS data folders

      JATOS has a couple of data folders. For easier backups it makes sense to have them all in one extra 'data' folder. Then you can just backup this 'data' folder with whatever file backup mechanism suits you best.

    2. Backup MySQL/MariaDB

      If you use a MySQL or MariaDB database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.

    3. 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

    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.

    2. If you specified an extra 'data' folder 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.

    - +
    Skip to main content
    Version: 3.9.x

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    And there are dedicated pages for installation with Docker and Docker Compose.

    Installing JATOS as a Internet server usually involves exchanging the embedded database with a MySQL/MariaDB one and setting up a reverse proxy (mostly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.

    Install Java​

    JATOS needs Java 11 to run (higher versions are not yet supported). You can install your own Java or get a JATOS that is already bundled with Java.

    Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Run JATOS:

      ./loader.sh start

      And to stop it:

      Usually Ctr+C does the job, but if your JATOS runs in the background:

      ./loader.sh stop

    5. Check JATOS is running correctly:

      Use curl: curl http://localhost:9000/ping should give you pong back

      If you can already access your server from the outside, open JATOS in a browser (the default port is 9000): http://my-IP-or-domain:9000. It should show the JATOS login screen. You can log in with username admin and password admin.

      Check JATOS' Administration page: http://my-IP-or-domain/jatos/admin. Click the Tests button: all tests should show an 'OK'. Click on System Info and check that all is like you configured it.

    6. Always change admin's password

      This can be done in JATOS' GUI:

      1. In a browser go to JATOS' login page http://my-IP-or-domain/jatos
      2. Log in as 'admin' with password 'admin'
      3. Click on Admin (admin) in top-right header
      4. Click Change Password

    [Optional] Install MySQL/MariaDB​

    See JATOS with MySQL

    Configuration​

    These docs have an extra page on JATOS Configuration. E.g. you can add user authentication with ORCID (orcid.org), OpenID Connect (OIDC), LDAP, or Google Sign-in.

    [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    [Optional] Specify the location of JATOS' data folders​

    By default all data folders are located in JATOS installation folder. But sometimes it is better to change the location to better suit your needs, e.g. for easier backups or updates.

    JATOS' data folders (and their path configuration):

    One might want to move all data folders in one extra 'data' folder. E.g. in JATOS' config file the following properties have to be set:

    jatos.studyAssetsRootPath = "/path/to/my/jatos-data-folder/study_assets_root"
    jatos.resultUploads.path =  "/path/to/my/jatos-data-folder/result_uploads"
    jatos.studyLogs.path =      "/path/to/my/jatos-data-folder/study_logs"

    Or with command-line arguments this would be:

    -Djatos.studyAssetsRootPath="/path/to/my/jatos-data-folder/study_assets_root" -Djatos.resultUploads.path="/path/to/my/jatos-data-folder/result_uploads" -Djatos.studyLogs.path="/path/to/my/jatos-data-folder/study_logs"

    [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularly.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the data folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to stop JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    1. JATOS data folders

      JATOS has a couple of data folders. For easier backups it makes sense to have them all in one extra 'data' folder. Then you can just backup this 'data' folder with whatever file backup mechanism suits you best.

    2. Backup MySQL/MariaDB

      If you use a MySQL or MariaDB database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.

    3. 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

    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.

    2. If you specified an extra 'data' folder 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/JATOS-with-Apache.html b/JATOS-with-Apache.html index 2fc2b5a44..2e61a5f0d 100644 --- a/JATOS-with-Apache.html +++ b/JATOS-with-Apache.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS with Apache

    This is an example of a configuration of Apache 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 from the Electronic Frontier Foundation.

    You have to add some modules to Apache to get it working:

    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 <Location "/jatos"> and config your local network. This will restrict the access to JATOS' GUI (every URL starting with /jatos) to the local network.

    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # 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/
    </VirtualHost>
    - +
    Skip to main content
    Version: 3.9.x

    JATOS with Apache

    This is an example of a configuration of Apache 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 from the Electronic Frontier Foundation.

    You have to add some modules to Apache to get it working:

    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 <Location "/jatos"> and config your local network. This will restrict the access to JATOS' GUI (every URL starting with /jatos) to the local network.

    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # 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/
    </VirtualHost>
    + \ No newline at end of file diff --git a/JATOS-with-Docker-Compose.html b/JATOS-with-Docker-Compose.html index bd611a718..15565ed93 100644 --- a/JATOS-with-Docker-Compose.html +++ b/JATOS-with-Docker-Compose.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS with Docker Compose

    Docker 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 that you can clone and then change them to your needs to get a JATOS installation running with docker compose. 

    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 starts three services:

    1. Nginx as a reverse proxy that does encryption (HTTPS)
    2. JATOS
    3. 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
    2. jatos-logs - for JATOS logs (not necessary if you log to stdout)
    3. jatos-db - where MySQL stores its data

    Up​

    Go into the cloned folder and start the services with:

    docker compose -f compose.yaml up

    If everything went smoothly, you will now see the JATOS login page under: 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. 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) 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 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. 

    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 with --skip-log-bin in db's command section.

    Check JATOS with MySQL for more information.

    JATOS configuration​

    Have a look at JATOS Configuration.

    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 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 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.

    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. 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.

    - +
    Skip to main content
    Version: 3.9.x

    JATOS with Docker Compose

    Docker 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 that you can clone and then change them to your needs to get a JATOS installation running with docker compose. 

    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 starts three services:

    1. Nginx as a reverse proxy that does encryption (HTTPS)
    2. JATOS
    3. 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
    2. jatos-logs - for JATOS logs (not necessary if you log to stdout)
    3. jatos-db - where MySQL stores its data

    Up​

    Go into the cloned folder and start the services with:

    docker compose -f compose.yaml up

    If everything went smoothly, you will now see the JATOS login page under: 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. 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) 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 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. 

    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 with --skip-log-bin in db's command section.

    Check JATOS with MySQL for more information.

    JATOS configuration​

    Have a look at JATOS Configuration.

    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 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 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.

    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. 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.

    + \ No newline at end of file diff --git a/JATOS-with-MySQL.html b/JATOS-with-MySQL.html index ca70f34c4..55ab89201 100644 --- a/JATOS-with-MySQL.html +++ b/JATOS-with-MySQL.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS with MySQL

    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. One way to set up MySQL:

    1. Install MySQL

      E.g. on Ubuntu

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      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.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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:

        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.

    2. 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:

        -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:

        ./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).

    3. 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:

      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):

    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.

    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). 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:

    # 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 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:

    max_allowed_packet=64M

    You have to restart the database for the changes to take effect.

    - +
    Skip to main content
    Version: 3.9.x

    JATOS with MySQL

    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. One way to set up MySQL:

    1. Install MySQL

      E.g. on Ubuntu

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      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.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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:

        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.

    2. 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:

        -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:

        ./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).

    3. 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:

      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):

    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.

    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). 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:

    # 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 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:

    max_allowed_packet=64M

    You have to restart the database for the changes to take effect.

    + \ No newline at end of file diff --git a/JATOS-with-Nginx.html b/JATOS-with-Nginx.html index 30655df47..3d80356bc 100644 --- a/JATOS-with-Nginx.html +++ b/JATOS-with-Nginx.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    JATOS with Nginx

    Here is an example for a configuration of Nginx 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 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.

    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;
            }
        }
    }
    - +
    Skip to main content
    Version: 3.9.x

    JATOS with Nginx

    Here is an example for a configuration of Nginx 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 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.

    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/JATOS_Configuration.html b/JATOS_Configuration.html index 9db431fe3..c123c6ae8 100644 --- a/JATOS_Configuration.html +++ b/JATOS_Configuration.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    JATOS Configuration

    JATOS' properties can be configured in three different ways:

    1. via a config file (named jatos.conf or production.conf)
    2. via command-line arguments
    3. 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. 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:

    ./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:

      jatos.http.address = 1.2.3.4
      jatos.http.port = 80

    2. 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:

      -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:

      play.server.http.idleTimeout = 100s

    2. Via command-line argument -Dplay.server.http.idleTimeout

      Example:

      -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:

      play.server.akka.requestTimeout = 100s

    2. Via command-line argument -Dplay.server.akka.requestTimeout

      Example:

      -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 (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:

      jatos.urlBasePath = "/mybasepath/"

    2. Via command-line arguments

      • For v3.8.1 and lower) -Dplay.http.context
      • For v3.8.2 and higher) -Djatos.urlBasePath
      -Djatos.urlBasePath="/mybasepath/"

    3. Via environment variable JATOS_URL_BASE_PATH

      JATOS_URL_BASE_PATH="/mybasepath/"

    X-Frame-Options header​

    The X-Frame-Options header can be used to allow or disallow embedding a JATOS study in an 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:

      play.filters.headers.frameOptions = null

    2. Via command-line argument -Dplay.filters.headers.frameOptions

      Example:

      -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

      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

      jatos.studyAssetsRootPath = "/path/to/my/assets/root/folder"

    2. Via command-line argument -Djatos.studyAssetsRootPath

      -Djatos.studyAssetsRootPath="/path/to/my/assets/root/folder"

    3. Via environment variable JATOS_STUDY_ASSETS_ROOT_PATH

      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

      jatos.tmpPath = "/my/tmp/dir"

    2. Via command-line argument -Djatos.tmpPath

      -Djatos.tmpPath="/my/tmp/dir"

    3. Via environment variable JATOS_TMP_PATH

      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.

    Application logs path​

    The application logs are by default in the JATOS folder under ./logs.

    1. Via config file property jatos.logs.path

      jatos.logs.path = "/my/dir/logs"

    2. Via command-line argument -Djatos.logs.path

      -Djatos.logs.path="/my/dir/logs"

    3. Via environment variable JATOS_LOGS_PATH

      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

      jatos.logs.filename = "myFilename"

    2. Via command-line argument -Djatos.logs.filename

      -Djatos.logs.filename="myFilename"

    3. Via environment variable JATOS_LOGS_FILENAME

      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

      jatos.logs.appender = ASYNCSTDOUT

    2. Via command-line argument -Djatos.logs.appender

      -Djatos.logs.appender=ASYNCSTDOUT

    3. Via environment variable JATOS_LOGS_APPENDER

      JATOS_LOGS_APPENDER=ASYNCSTDOUT

    Study logs​

    Every study stored in JATOS has its own study log (more info). 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. .

    Enable/disable study logging​

    By default study logging is enabled.

    1. Via config file property jatos.studyLogs.enabled

      jatos.studyLogs.enabled = false

    2. Via command-line argument -Djatos.studyLogs.enabled

      -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

      jatos.studyLogs.path = "/path/to/my/jatos_study_logs"

    2. Via command-line argument -Djatos.studyLogs.path

      -Djatos.studyLogs.path="/path/to/my/jatos_study_logs"

    3. Via environment variable JATOS_STUDY_LOGS_PATH

      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

      jatos.studyMembers.allowAddAllUsers = true

    2. Via command-line argument -Djatos.studyMembers.allowAddAllUsers

      -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

      jatos.maxResultsDbQuerySize = 5

    2. Via command-line argument -Djatos.maxResultsDbQuerySize

      -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

      jatos.resultData.maxSize = 10MB

    2. Via command-line argument -Djatos.resultData.maxSize

      -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

      jatos.resultUploads.enabled = false

    2. Via command-line argument -Djatos.resultUploads.enabled

      -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

      jatos.resultUploads.path = "/path/to/my/jatos_result_uploads"

    2. Via command-line argument -Djatos.resultUploads.path

      -Djatos.resultUploads.path="/path/to/my/jatos_result_uploads"

    3. Via environment variable JATOS_RESULT_UPLOADS_PATH

      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

      jatos.resultUploads.maxFileSize = 100MB

    2. Via command-line argument -Djatos.resultUploads.maxFileSize

      -Djatos.resultUploads.maxFileSize=100MB

    3. Via environment variable JATOS_RESULT_UPLOADS_MAX_FILE_SIZE

      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

      jatos.resultUploads.limitPerStudyRun = 100MB

    2. Via command-line argument -Djatos.resultUploads.limitPerStudyRun

      -Djatos.resultUploads.limitPerStudyRun=100MB

    3. Via environment variable JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN

      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

      jatos.user.role.allowSuperuser = true

    2. Via command-line argument -Djatos.user.role.allowSuperuser

      -Djatos.user.role.allowSuperuser=true

    LDAP authentication​

    At the moment LDAP users still have to be added manually in JATOS' User manager (with the switch 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).

    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

      jatos.user.authentication.ldap.url = "ldap://my.ldap.org:389"

    2. Via command-line argument -Djatos.user.authentication.ldap.url

      -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

      jatos.user.authentication.ldap.basedn = "dc=example,dc=com"

    2. Via command-line argument -Djatos.user.authentication.ldap.basedn

      -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

      jatos.user.authentication.ldap.admin.dn = "cn=read-only-admin,dc=example,dc=com"
      jatos.user.authentication.ldap.admin.password = "mypassword"

    2. Via command-line arguments -Djatos.user.authentication.ldap.admin.dn and -Djatos.user.authentication.ldap.admin.password

      -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

      jatos.user.authentication.ldap.timeout = 10000

    2. Via command-line argument -Djatos.user.authentication.ldap.timeout

      -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.

    1. Via config file property jatos.user.authentication.oauth.googleClientId

      jatos.user.authentication.oauth.googleClientId = "1234567890-abc123abc123.apps.googleusercontent.com"

    2. Via command-line argument -Djatos.user.authentication.oauth.googleClientId

      -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.

    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

      jatos.user.authentication.oidc.discoveryUrl = "http://myOidcProvider/.well-known/openid-configuration"

    2. Via command-line argument -Djatos.user.authentication.oidc.discoveryUrl

      -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

      jatos.user.authentication.oidc.clientId = "myClientId"

    2. Via command-line argument -Djatos.user.authentication.oidc.clientId

      -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

      jatos.user.authentication.oidc.clientSecret = "myClientSecret"

    2. Via command-line argument -Djatos.user.authentication.oidc.clientSecret

      -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

      jatos.user.authentication.oidc.idTokenSigningAlgorithm = "ES512"

    2. Via command-line argument -Djatos.user.authentication.oidc.idTokenSigningAlgorithm

      -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

      jatos.user.authentication.oidc.signInButtonText = "Sign in with ABC university"

    2. Via command-line argument -Djatos.user.authentication.oidc.signInButtonText

      -Djatos.user.authentication.oidc.signInButtonText="Sign in with ABC university"

    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

      jatos.user.authentication.oidc.signInButtonLogoUrl = "http://somedomain/logo.svg"

    2. Via command-line argument -Djatos.user.authentication.oidc.signInButtonLogoUrl

      -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

      jatos.user.authentication.oidc.successFeedback = "You successfully signed in with ABC university"

    2. Via command-line argument -Djatos.user.authentication.oidc.successFeedback

      -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. Internally ORCID uses OpenId Connect.

    ORCID client ID​

    Specifies your ORCID client ID.

    1. Via config file property jatos.user.authentication.orcid.clientId

      jatos.user.authentication.orcid.clientId = "APP-ABCDEFGHIJKLMNOP"

    2. Via command-line argument -Djatos.user.authentication.orcid.clientId

      -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

      jatos.user.authentication.orcid.clientSecret = "1234abcd-12ab-12ab-12ab-123456abcdef"

    2. Via command-line argument -Djatos.user.authentication.orcid.clientSecret

      -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

      jatos.user.password.length = 8

    2. Via command-line argument -Djatos.user.password.length

      -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

      jatos.user.password.strength = 3

    2. Via command-line argument -Djatos.user.password.strength

      -Djatos.user.password.strength=3

    Database​

    See JATOS with MySQL.

    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

      jatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"

    2. Via command-line argument -Djatos.db.url

      -Djatos.db.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"

    3. Via environment variable JATOS_DB_URL

      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

      jatos.db.username = "myusername"
      jatos.db.password = "mypassword"

    2. Via command-line argument -Djatos.db.username and -Djatos.db.password

      -Djatos.db.username = "myusername" -Djatos.db.password = "mypassword"

    3. Via environment variable JATOS_DB_USERNAME and JATOS_DB_PASSWORD

      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

      jatos.db.driver = "com.mysql.cj.jdbc.Driver"

    2. Via command-line argument -Djatos.db.driver

      -Djatos.db.driver="com.mysql.cj.jdbc.Driver"

    3. Via environment variable JATOS_DB_DRIVER

      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

      jatos.multiNode = true

    2. Via command-line argument -Djatos.multiNode

      -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

      jatos.userSession.timeout = 180

    2. Via command-line argument -Djatos.userSession.timeout

      -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

      jatos.userSession.inactivity = 120

    2. Via command-line argument -Djatos.userSession.inactivity

      -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

      play.http.session.secure = true

    2. Via command-line argument -Dplay.http.session.secure

      -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

      jatos.idCookies.secure = true

    2. Via command-line argument -Djatos.idCookies.secure

      -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

      jatos.idCookies.sameSite = "Lax"

    2. Via command-line argument -Djatos.idCookies.sameSite

      -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

      play.pidfile.path = "/var/run/jatos.pid"

    2. Via command-line argument -Dplay.pidfile.path

      -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). If left empty ("") the default welcome message is shown. Default is empty.

    1. Via config file property jatos.brandingUrl

      jatos.brandingUrl = "https://mydomain.com/foobar-university-welcome-page.html"

    2. Via command-line argument -Djatos.brandingUrl

      -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

      jatos.termsOfUseUrl = "https://mydomain.com/my-terms-of-use.html"

    2. Via command-line argument -Djatos.termsOfUseUrl

      -Djatos.termsOfUseUrl = "https://mydomain.com/my-terms-of-use.html"

    Study manager page​

    Enable/disable some columns in the study manager 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

      jatos.studyAdmin.showStudyAssetsSize = false # Default is true
      jatos.studyAdmin.showResultDataSize = true # Default is false
      jatos.studyAdmin.showResultFileSize = true # Default is false

    2. Via command-line arguments -Djatos.studyAdmin.showStudyAssetsSize, -Djatos.studyAdmin.showResultDataSize, and -Djatos.studyAdmin.showResultFileSize

      -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

      jatos.api.allowed = false

    2. Via command-line argument -Djatos.api.allowed

      -Djatos.api.allowed = false
    - +due to a slow database or file system.

    1. Via config file properties jatos.studyAdmin.showStudyAssetsSize, jatos.studyAdmin.showResultDataSize, and jatos.studyAdmin.showResultFileSize

      jatos.studyAdmin.showStudyAssetsSize = false # Default is true
      jatos.studyAdmin.showResultDataSize = true # Default is false
      jatos.studyAdmin.showResultFileSize = true # Default is false

    2. Via command-line arguments -Djatos.studyAdmin.showStudyAssetsSize, -Djatos.studyAdmin.showResultDataSize, and -Djatos.studyAdmin.showResultFileSize

      -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

      jatos.api.allowed = false

    2. Via command-line argument -Djatos.api.allowed

      -Djatos.api.allowed = false
    + \ No newline at end of file diff --git a/Manage-Results.html b/Manage-Results.html index db3e375ad..40e22d283 100644 --- a/Manage-Results.html +++ b/Manage-Results.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Manage results

    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

    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

    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

    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

    Filter results & filter builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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 elaborate 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

    Export results​

    Results View screenshot

    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

    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).

    Export result data​

    Results View screenshot

    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

    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

    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

    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

    • 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.

    • 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 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 (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 or jatos.abortStudy.

    - +
    Skip to main content
    Version: 3.9.x

    Manage results

    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

    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

    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

    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

    Filter results & filter builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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 elaborate 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

    Export results​

    Results View screenshot

    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

    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).

    Export result data​

    Results View screenshot

    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

    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

    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

    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

    • 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.

    • 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 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 (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 or jatos.abortStudy.

    + \ No newline at end of file diff --git a/OSWeb-and-JATOS.html b/OSWeb-and-JATOS.html index 3036cec25..2abbf9a39 100644 --- a/OSWeb-and-JATOS.html +++ b/OSWeb-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    - +
    Skip to main content
    Version: 3.9.x

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    + \ No newline at end of file diff --git a/Papers-Citing-JATOS.html b/Papers-Citing-JATOS.html index 2d00349f5..94f4b4b2f 100644 --- a/Papers-Citing-JATOS.html +++ b/Papers-Citing-JATOS.html @@ -10,14 +10,14 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Papers citing JATOS

    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.)

    Please cite us 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 on how (much) you use JATOS (ca. 3 min). It’s very important for us!

    2024​

    Conson, M., Zappullo, I., Cordasco, G., Trojano, L., Raimo, G., Cecere, R., Baiano, C., Lauro, A., & Esposito, A. (2024). Altercentrism in perspective-taking: The role of humanisation in embodying the agent’s point of view. Quarterly Journal of Experimental Psychology. DOI

    Pucci, V., Contemori, G., Saccani, M.S. et al. (2024) Auto-Global Examination of Mental State (Auto-GEMS): a web-based self-administered cognitive screening. Aging Clin Exp Res. DOI

    Wiradhany, W., Pócs, A., Baumgartner, S.E. (2024) Are Social Media Notifications Distracting? Experimental Psychology DOI

    Russell, M.D., Bonny, J.W., Reed, R. (2024) Impact of Virtual Reality on Decision-Making and Risk Assessment During Simulated Residential Fire Scenarios. Fire DOI

    Nakamura, S., Kobayashi, M. (2024) Examining psychological detachment from work, work engagement, and thought control in Japanese work at home environments. Discov Psychol DOi

    Duncan, D.H., van Moorselaar, D. & Theeuwes, J. (2024) Visual statistical learning requires attention. Psychon Bull Rev DOI

    Hasenäcker, J., & Domahs, F. (2024). EXPRESS: Same same but different – The graded influence of vowel quality and prosodic prominence on letter detection. Quarterly Journal of Experimental Psychology. DOI

    Godwin, H. J., Liversedge, S. P., Mestry, N., Dewis, H., & Donnelly, N. (2024). Time on task effects during interactive visual search. Journal of Experimental Psychology: Applied. DOI

    Schreiner, M.R., Feustel, S. & Kunde, W. (2024) Linking actions and memories: Probing the interplay of action-effect congruency, agency experience, and recognition memory. Mem Cogn. DOI

    de Valério de Arruda, M., Reyes, M. B., das Neves, S. F., Herrmann, F., Verzili, B., & Galduróz, R. F. (2024). Temporal bisection task as a predictor of cognitive deficits. European Journal of Neuroscience. DOI

    Xu, X., Zhu, Z., Zheng, X. et al. (2024) Temporal asymmetries in inferring unobserved past and future events. Nat Commun. DOI

    Wainio-Theberge, S., & Armony, J. L. (2024). Differences in natural standing posture are associated with antisocial and manipulative personality traits. Journal of Personality and Social Psychology. DOI

    Embon, I., Gerbaudo, M.A., Usaj, A.R. et al. (2024) Exploring the relationship between dysfunctional personality traits with metacognition and confidence. Curr Psychol. DOI

    Di Ponzio, M., Battaglini, L., Bertamini, M. et al. (2024) Behavioural stochastic resonance across the lifespan. Cogn Affect Behav Neurosci DOI

    Caudrelier, T., Ménard, L. Beausoleil, M.M., Martin, C.D., Samuel, A.G. (2024) When Jack isn’t Jacques: Simultaneous opposite language-specific speech perceptual learning in French–English bilinguals. PNAS Nexus DOI

    Shum, Y.H., Galang, C.M.,Brass, M. (2024) Using a Veto paradigm to investigate the decision models in explaining Libet-style experiments. Consciousness and Cognition DOI

    Kim, M., Kim, K.I. & Kim, H. (2024) Self-interest overrides rank-reversal aversion in resource distribution. Sci Rep. DOI

    Bonny, J.W., Hussain, Z., Russell, M.D., Trouvé A., Milke J.A. (2024) Simulated fire video collection for advancing understanding of human behavior in building fires. Frontiers in Psychology. DOI

    Duncan, D. H., & Theeuwes, J. (2024). Secondary capture: Salience information persistently drives attentional selection. Journal of Experimental Psychology: Human Perception and Performance. DOI

    Li, AS., van Moorselaar, D. & Theeuwes, J. (2024) Attending is not enough: Responding to targets is needed for across-trial statistical learning. Atten Percept Psychophys. DOI

    Pithayarungsarit, P., Rieger, T., Onnasch, L., & Roesler, E. (2024). The Pop-Out Effect of Rarer Occurring Stimuli Shapes the Effectiveness of AI Explainability. Proceedings of the Human Factors and Ergonomics Society Annual Meeting. DOI

    zu Putlitz, J., & Roesler, E. (2024). Let’s Get Physical: The Influence of Embodiment on Industrial Human-Robot Interaction. Proceedings of the Human Factors and Ergonomics Society Annual Meeting DOI

    Brouwer, J., van den Berg, F., Knooihuizen, R., Loerts, H., & Keijzer, M. (2024). The effects of language learning on cognitive functioning and psychosocial well-being in cognitively healthy older adults: A semi-blind randomized controlled trial. Aging, Neuropsychology, and Cognition. DOI

    Frugarello, P., Rusconi, E., Job, R. (2024) The label-feedback effect is influenced by target category in visual search. PLoS ONE. DOI

    Bauer, R., Jansen, P. (2024) A short mindfulness induction might increase women’s mental rotation performance. Consciousness and Cognition DOI

    Xue, S., Gao, X., Wu, Y., Sun, J., Yang, W., Li, X., Ke, S., Yang, L., Jin, H., & Chen, S. (2024). Effects of Theme, Form, and Language on Poetry Reading: Evidence From Chinese ESL Learners. Empirical Studies of the Arts. DOI

    Niedernhuber M, Streicher J, Leggenhager B, Bekinschtein TA. (2024) Attention and Interoception Alter Perceptual and Neural Pain Signatures-A Case Study. J Pain Res. DOI

    Schmerwitz, C., Kopp, B. (2024) The future of neuropsychology is digital, theory-driven, and Bayesian: a paradigmatic study of cognitive flexibility. Frontiers in Psychology DOI

    Loaiza, V.M., Souza, A.S. (2024) Active maintenance in working memory reinforces bindings for future retrieval from episodic long-term memory. Mem Cogn. DOI

    Winkelmair, A., Jansen, P. (2024) Can a mindfulness-based training influence explicit and implicit attitudes, as well as sustainable nutrition behaviors, particularly in relation to vegetarianism?. Appetite DOI

    Contemori G., Saccani M.S., Bonato M. (2024) Cognitive-Cognitive Dual-task in aging: A cross-sectional online study. PLoS ONE. DOI

    Gemignani, M., Giannotti, M., Rigo, P. et al. (2024) Neither Parents’ Sex Nor the Type of Family Modulates Attentional Bias Toward Infant Faces: A Preliminary Study in Different-Sex and Same-Sex Parents. Arch Sex Behav. DOI

    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

    Berkovich, R., & Meiran, N. (2024). Both pleasant and unpleasant emotional feelings follow Weber’s law but it depends how you ask. Emotion DOI

    Oz-Cohen, E., Berkovich, R. & Meiran, N. (2024) Bumpy ride ahead: Anticipated effort as emotional evidence?. Cogn Affect Behav Neurosci. DOI

    van Moorselaar, D., & Theeuwes, J. (2024). Transfer of statistical learning between tasks. Journal of Experimental Psychology: Human Perception and Performance. DOI

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Theeuwes, J., Huang, C., Frings, C., & van Moorselaar, D. (2024). Statistical learning of motor preparation. Journal of Experimental Psychology: Human Perception and Performance. DOI

    Corradi G, Aguilar P, Aguiar F, Olivera-La Rosa A (2024) Age and moral disgust: An experimental priming effects vignette study. PLoS ONE DOI

    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

    Bognar, M., Szekely, Z., Varga, M.A. et al. (2024 )Cognitive control adjustments are dependent on the level of conflict. Sci Rep DOI

    van Moorselaar D, Theeuwes J. (2024) Spatial transfer of object-based statistical learning. Atten Percept Psychophys DOI

    Lallement, C., Lemaire, P. (2024) Are There Age-Related Differences in Effects of Positive and Negative Emotions in Arithmetic? Experimental Psychology DOI

    Vandendaele, A., Prutean, N. and Declerck, M. (2024). A Blessing in Disguise: Flanking Words Can Cancel Language Switch Costs. Journal of Cognition DOI

    Moore, C.M., Zheng, Q. (2024) Limited midlevel mediation of visual crowding: Surface completion fails to support uncrowding. Journal of Vision DOI

    Oppenheim, G.M., Nozari, N. (2024) Similarity-induced interference or facilitation in language production reflects representation, not selection. Cognition DOI

    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

    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

    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

    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

    Mu, Y., Schubö, A. & Tünnermann, J. (2024) Adapting attentional control settings in a shape-changing environment. Atten Percept Psychophys. DOI

    Shyr, M.C., Joshi, S.S. (2024) A Case Study of the Validity of Web-based Visuomotor Rotation Experiments. J Cogn Neurosci DOI

    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

    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

    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

    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

    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

    Curzel, F., Carraturo, G., Ripollés, P., & Ferreri, L. (2023). Better off alone? When sharing music reduces pleasure responses. Advances in Cognitive Psychology. DOI

    Fahnenstich, H., Rieger, T., Roesler, E. (2023). Trusting under risk – comparing human to AI decision support agents. Computers in Human Behavior DOI

    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

    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

    Palmer, C. J., Kim, P., & Clifford, C. W. G. (2023). Gaze behavior as a visual cue to animacy. Journal of Experimental Psychology: General. DOI

    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

    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

    Wang, X., Li, X., Yin, Z., Wu, Y., & Liu, J. (2023). Emotional intelligence of Large Language Models. Journal of Pacific Rim Psychology. DOI

    Marks, R.A., Eggleston, R., Kovelman, I. (2023) Brain bases of morphological awareness and longitudinal word reading outcomes. Journal of Experimental Child Psychology. DOI

    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

    Oberholzer, Y., Olschewski, S., Scheibehenne, B. Complexity Aversion in Risky Choices and Valuations: Moderators and Possible Causes. Journal of Economic Psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    Vandendaele, A., & Grainger, J. (2023). Lexical competition in the flankers task revised. PLoS one DOI

    Labaronne, M., Ferreri, L. & Plancher, G. (2023) How do intentions modulate the effect of working memory on long-term memory? Psychon Bull Rev. DOI

    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

    Constant, M., Pereira, M., Faivre, N. et al. (2023) Prior information differentially affects discrimination decisions and subjective confidence reports. Nat Commun. DOI

    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

    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

    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

    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

    Sobczak, A., Bunzeck, N. (2023) Effects of positive and negative social feedback on motivation, evaluative learning, and socio-emotional processing. npj Sci. Learn. DOI

    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

    Ivanov, Y., Theeuwes, J. & Bogaerts, L. (2023) Reliability of individual differences in distractor suppression driven by statistical learning. Behav Res. DOI

    Wang-Ly, Nathan and Newell, Ben R. (2023) Uncertain goals and savings adequacy: Contrasting economic and psychological perspectives. SSRN DOI

    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

    de Waard, J., van Moorselaar, D., Bogaerts, L. et al. (2023) Statistical learning of distractor locations is dependent on task context. Sci Rep DOI

    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

    Jansen, P., Rahe, M., Hoja, S. et al. (2023) Are Character Strengths and Attitudes towards Vegetarian Food Related? Int J Appl Posit Psychol. DOI

    Kahan, T.A., Smith, Z.P. (2023) Effects of alerting signals on the spatial Stroop effect: evidence for modality differences. Psychological Research. DOI

    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

    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

    Xie, T., Fu, S. & Mento, G. (2023) Faces do not guide attention in an object-based facilitation manner. Atten Percept Psychophys. DOI

    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

    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

    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

    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

    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

    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

    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

    Gao, Y., de Waard, J. & Theeuwes, J. (2023) Learning to suppress a location is configuration-dependent. Atten Percept Psychophys DOI

    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

    Ng, D. W., Lee, J. C., & Lovibond, P. F. (2023). Unidirectional rating scales overestimate the illusory causation phenomenon. Quarterly Journal of Experimental Psychology DOI

    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

    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

    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

    Tian, J., Ren, K., Gunderson, EA. (2023) Verbal labels influence children's processing of decimal magnitudes. Journal of Applied Developmental Psychology DOI

    Bognar, M., Gyurkovics, M., van Steenbergen, H. & Aczel, B. (2023) Phasic affective signals by themselves do not regulate cognitive control. Cognition and Emotion DOI

    Huang, C., Donk, M. & Theeuwes, J. (2023) Attentional suppression is in place before display onset. Atten Percept Psychophys. DOI

    Salava, A, Salmela, V. (2023) Perceptual learning in dermatology—A Finnish cohort study of undergraduate medical students. J Eur Acad Dermatol Venereol. DOI

    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

    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

    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

    Dijkstra, N., Fleming, S.M. (2023) Subjective signal strength distinguishes reality from imagination. Nat Commun DOI

    Guseva, M., Bogler, C., Allefeld C., Haynes JD. (2023) Instruction effects on randomness in sequence generation. Frontiers in Psychology. DOI

    van Moorselaar, D., & Theeuwes, J. (2023). Statistical Learning Within Objects. Psychological Science DOI

    Lu, Z., van Zoest, W. (2023) Combining social cues in attention: Looking at gaze, head, and pointing cues. Atten Percept Psychophys. DOI

    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

    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

    Reichardt, R., Polner, B., & Simor, P. (2023). Influencing prior knowledge through a short reading impacts curiosity and learning. Applied Cognitive Psychology DOI

    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

    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

    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

    Lee, M.D., Stark, C.E.L. (2023) Bayesian modeling of the Mnemonic Similarity Task using multinomial processing trees. Behaviormetrika DOI

    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

    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

    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

    Zoefel B, Gilbert RA, Davis MH (2023) Intelligibility improves perception of timing changes in speech. PLoS ONE DOI

    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

    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

    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

    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

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys DOI

    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

    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

    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

    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

    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

    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

    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

    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

    Wittmann BC, Şatırer Y. (2022) Decreased associative processing and memory confidence in aphantasia. Learn Mem. DOI

    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

    Mueckstein, M., Heinzel, S., Granacher, U., Brahms, M., Rapp, MA., Stelzel, C. (2022) Modality-specific effects of mental fatigue in multitasking, Acta Psychologica DOI

    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

    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

    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

    Radović T, Rieger T and Manzey D (2022) A global and local perspective of interruption frequency in a visual search task. Front. Psychol. DOI

    Vos, M., Minor, S., & Ramchand, G. C. (2022). Comparing infrared and webcam eye tracking in the Visual World Paradigm. Glossa Psycholinguistics DOI

    Tsang, K. Y., & Mannion, D. J. (2022). Relating Sound and Sight in Simulated Environments. Multisensory Research DOI

    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

    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

    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

    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

    Contemori, G., Saccani, MS., Bonato, M. (2022) Multitasking Effects on Perception and Memory in Older Adults. Vision DOI

    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

    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

    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

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    - +
    Skip to main content
    Version: 3.9.x

    Papers citing JATOS

    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.)

    Please cite us 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 on how (much) you use JATOS (ca. 3 min). It’s very important for us!

    2024​

    Roesler, E., Rieger, T. Langer, M. (2024) Numeric vs. verbal information: The influence of information quantifiability in Human-AI vs. Human-Human decision support, Computers in Human Behavior: Artificial Humans DOI

    Banh N.C., Tünnermann J., Rohlfing K.J., Scharlau, I. (2024) Benefiting from binary negations? Verbal negations decrease visual attention and balance its distribution. Front. Psychol. DOI

    Conson, M., Zappullo, I., Cordasco, G., Trojano, L., Raimo, G., Cecere, R., Baiano, C., Lauro, A., & Esposito, A. (2024). Altercentrism in perspective-taking: The role of humanisation in embodying the agent’s point of view. Quarterly Journal of Experimental Psychology. DOI

    Pucci, V., Contemori, G., Saccani, M.S. et al. (2024) Auto-Global Examination of Mental State (Auto-GEMS): a web-based self-administered cognitive screening. Aging Clin Exp Res. DOI

    Wiradhany, W., Pócs, A., Baumgartner, S.E. (2024) Are Social Media Notifications Distracting? Experimental Psychology DOI

    Russell, M.D., Bonny, J.W., Reed, R. (2024) Impact of Virtual Reality on Decision-Making and Risk Assessment During Simulated Residential Fire Scenarios. Fire DOI

    Nakamura, S., Kobayashi, M. (2024) Examining psychological detachment from work, work engagement, and thought control in Japanese work at home environments. Discov Psychol DOi

    Duncan, D.H., van Moorselaar, D. & Theeuwes, J. (2024) Visual statistical learning requires attention. Psychon Bull Rev DOI

    Hasenäcker, J., & Domahs, F. (2024). EXPRESS: Same same but different – The graded influence of vowel quality and prosodic prominence on letter detection. Quarterly Journal of Experimental Psychology. DOI

    Godwin, H. J., Liversedge, S. P., Mestry, N., Dewis, H., & Donnelly, N. (2024). Time on task effects during interactive visual search. Journal of Experimental Psychology: Applied. DOI

    Schreiner, M.R., Feustel, S. & Kunde, W. (2024) Linking actions and memories: Probing the interplay of action-effect congruency, agency experience, and recognition memory. Mem Cogn. DOI

    de Valério de Arruda, M., Reyes, M. B., das Neves, S. F., Herrmann, F., Verzili, B., & Galduróz, R. F. (2024). Temporal bisection task as a predictor of cognitive deficits. European Journal of Neuroscience. DOI

    Xu, X., Zhu, Z., Zheng, X. et al. (2024) Temporal asymmetries in inferring unobserved past and future events. Nat Commun. DOI

    Wainio-Theberge, S., & Armony, J. L. (2024). Differences in natural standing posture are associated with antisocial and manipulative personality traits. Journal of Personality and Social Psychology. DOI

    Embon, I., Gerbaudo, M.A., Usaj, A.R. et al. (2024) Exploring the relationship between dysfunctional personality traits with metacognition and confidence. Curr Psychol. DOI

    Di Ponzio, M., Battaglini, L., Bertamini, M. et al. (2024) Behavioural stochastic resonance across the lifespan. Cogn Affect Behav Neurosci DOI

    Caudrelier, T., Ménard, L. Beausoleil, M.M., Martin, C.D., Samuel, A.G. (2024) When Jack isn’t Jacques: Simultaneous opposite language-specific speech perceptual learning in French–English bilinguals. PNAS Nexus DOI

    Shum, Y.H., Galang, C.M.,Brass, M. (2024) Using a Veto paradigm to investigate the decision models in explaining Libet-style experiments. Consciousness and Cognition DOI

    Kim, M., Kim, K.I. & Kim, H. (2024) Self-interest overrides rank-reversal aversion in resource distribution. Sci Rep. DOI

    Bonny, J.W., Hussain, Z., Russell, M.D., Trouvé A., Milke J.A. (2024) Simulated fire video collection for advancing understanding of human behavior in building fires. Frontiers in Psychology. DOI

    Duncan, D. H., & Theeuwes, J. (2024). Secondary capture: Salience information persistently drives attentional selection. Journal of Experimental Psychology: Human Perception and Performance. DOI

    Li, AS., van Moorselaar, D. & Theeuwes, J. (2024) Attending is not enough: Responding to targets is needed for across-trial statistical learning. Atten Percept Psychophys. DOI

    Pithayarungsarit, P., Rieger, T., Onnasch, L., & Roesler, E. (2024). The Pop-Out Effect of Rarer Occurring Stimuli Shapes the Effectiveness of AI Explainability. Proceedings of the Human Factors and Ergonomics Society Annual Meeting. DOI

    zu Putlitz, J., & Roesler, E. (2024). Let’s Get Physical: The Influence of Embodiment on Industrial Human-Robot Interaction. Proceedings of the Human Factors and Ergonomics Society Annual Meeting DOI

    Brouwer, J., van den Berg, F., Knooihuizen, R., Loerts, H., & Keijzer, M. (2024). The effects of language learning on cognitive functioning and psychosocial well-being in cognitively healthy older adults: A semi-blind randomized controlled trial. Aging, Neuropsychology, and Cognition. DOI

    Frugarello, P., Rusconi, E., Job, R. (2024) The label-feedback effect is influenced by target category in visual search. PLoS ONE. DOI

    Bauer, R., Jansen, P. (2024) A short mindfulness induction might increase women’s mental rotation performance. Consciousness and Cognition DOI

    Xue, S., Gao, X., Wu, Y., Sun, J., Yang, W., Li, X., Ke, S., Yang, L., Jin, H., & Chen, S. (2024). Effects of Theme, Form, and Language on Poetry Reading: Evidence From Chinese ESL Learners. Empirical Studies of the Arts. DOI

    Niedernhuber M, Streicher J, Leggenhager B, Bekinschtein TA. (2024) Attention and Interoception Alter Perceptual and Neural Pain Signatures-A Case Study. J Pain Res. DOI

    Schmerwitz, C., Kopp, B. (2024) The future of neuropsychology is digital, theory-driven, and Bayesian: a paradigmatic study of cognitive flexibility. Frontiers in Psychology DOI

    Loaiza, V.M., Souza, A.S. (2024) Active maintenance in working memory reinforces bindings for future retrieval from episodic long-term memory. Mem Cogn. DOI

    Winkelmair, A., Jansen, P. (2024) Can a mindfulness-based training influence explicit and implicit attitudes, as well as sustainable nutrition behaviors, particularly in relation to vegetarianism?. Appetite DOI

    Contemori G., Saccani M.S., Bonato M. (2024) Cognitive-Cognitive Dual-task in aging: A cross-sectional online study. PLoS ONE. DOI

    Gemignani, M., Giannotti, M., Rigo, P. et al. (2024) Neither Parents’ Sex Nor the Type of Family Modulates Attentional Bias Toward Infant Faces: A Preliminary Study in Different-Sex and Same-Sex Parents. Arch Sex Behav. DOI

    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

    Berkovich, R., & Meiran, N. (2024). Both pleasant and unpleasant emotional feelings follow Weber’s law but it depends how you ask. Emotion DOI

    Oz-Cohen, E., Berkovich, R. & Meiran, N. (2024) Bumpy ride ahead: Anticipated effort as emotional evidence?. Cogn Affect Behav Neurosci. DOI

    van Moorselaar, D., & Theeuwes, J. (2024). Transfer of statistical learning between tasks. Journal of Experimental Psychology: Human Perception and Performance. DOI

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Theeuwes, J., Huang, C., Frings, C., & van Moorselaar, D. (2024). Statistical learning of motor preparation. Journal of Experimental Psychology: Human Perception and Performance. DOI

    Corradi G, Aguilar P, Aguiar F, Olivera-La Rosa A (2024) Age and moral disgust: An experimental priming effects vignette study. PLoS ONE DOI

    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

    Bognar, M., Szekely, Z., Varga, M.A. et al. (2024 )Cognitive control adjustments are dependent on the level of conflict. Sci Rep DOI

    van Moorselaar D, Theeuwes J. (2024) Spatial transfer of object-based statistical learning. Atten Percept Psychophys DOI

    Lallement, C., Lemaire, P. (2024) Are There Age-Related Differences in Effects of Positive and Negative Emotions in Arithmetic? Experimental Psychology DOI

    Vandendaele, A., Prutean, N. and Declerck, M. (2024). A Blessing in Disguise: Flanking Words Can Cancel Language Switch Costs. Journal of Cognition DOI

    Moore, C.M., Zheng, Q. (2024) Limited midlevel mediation of visual crowding: Surface completion fails to support uncrowding. Journal of Vision DOI

    Oppenheim, G.M., Nozari, N. (2024) Similarity-induced interference or facilitation in language production reflects representation, not selection. Cognition DOI

    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

    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

    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

    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

    Mu, Y., Schubö, A. & Tünnermann, J. (2024) Adapting attentional control settings in a shape-changing environment. Atten Percept Psychophys. DOI

    Shyr, M.C., Joshi, S.S. (2024) A Case Study of the Validity of Web-based Visuomotor Rotation Experiments. J Cogn Neurosci DOI

    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

    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

    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

    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

    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

    Curzel, F., Carraturo, G., Ripollés, P., & Ferreri, L. (2023). Better off alone? When sharing music reduces pleasure responses. Advances in Cognitive Psychology. DOI

    Fahnenstich, H., Rieger, T., Roesler, E. (2023). Trusting under risk – comparing human to AI decision support agents. Computers in Human Behavior DOI

    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

    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

    Palmer, C. J., Kim, P., & Clifford, C. W. G. (2023). Gaze behavior as a visual cue to animacy. Journal of Experimental Psychology: General. DOI

    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

    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

    Wang, X., Li, X., Yin, Z., Wu, Y., & Liu, J. (2023). Emotional intelligence of Large Language Models. Journal of Pacific Rim Psychology. DOI

    Marks, R.A., Eggleston, R., Kovelman, I. (2023) Brain bases of morphological awareness and longitudinal word reading outcomes. Journal of Experimental Child Psychology. DOI

    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

    Oberholzer, Y., Olschewski, S., Scheibehenne, B. Complexity Aversion in Risky Choices and Valuations: Moderators and Possible Causes. Journal of Economic Psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    Vandendaele, A., & Grainger, J. (2023). Lexical competition in the flankers task revised. PLoS one DOI

    Labaronne, M., Ferreri, L. & Plancher, G. (2023) How do intentions modulate the effect of working memory on long-term memory? Psychon Bull Rev. DOI

    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

    Constant, M., Pereira, M., Faivre, N. et al. (2023) Prior information differentially affects discrimination decisions and subjective confidence reports. Nat Commun. DOI

    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

    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

    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

    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

    Sobczak, A., Bunzeck, N. (2023) Effects of positive and negative social feedback on motivation, evaluative learning, and socio-emotional processing. npj Sci. Learn. DOI

    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

    Ivanov, Y., Theeuwes, J. & Bogaerts, L. (2023) Reliability of individual differences in distractor suppression driven by statistical learning. Behav Res. DOI

    Wang-Ly, Nathan and Newell, Ben R. (2023) Uncertain goals and savings adequacy: Contrasting economic and psychological perspectives. SSRN DOI

    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

    de Waard, J., van Moorselaar, D., Bogaerts, L. et al. (2023) Statistical learning of distractor locations is dependent on task context. Sci Rep DOI

    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

    Jansen, P., Rahe, M., Hoja, S. et al. (2023) Are Character Strengths and Attitudes towards Vegetarian Food Related? Int J Appl Posit Psychol. DOI

    Kahan, T.A., Smith, Z.P. (2023) Effects of alerting signals on the spatial Stroop effect: evidence for modality differences. Psychological Research. DOI

    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

    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

    Xie, T., Fu, S. & Mento, G. (2023) Faces do not guide attention in an object-based facilitation manner. Atten Percept Psychophys. DOI

    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

    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

    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

    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

    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

    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

    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

    Gao, Y., de Waard, J. & Theeuwes, J. (2023) Learning to suppress a location is configuration-dependent. Atten Percept Psychophys DOI

    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

    Ng, D. W., Lee, J. C., & Lovibond, P. F. (2023). Unidirectional rating scales overestimate the illusory causation phenomenon. Quarterly Journal of Experimental Psychology DOI

    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

    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

    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

    Tian, J., Ren, K., Gunderson, EA. (2023) Verbal labels influence children's processing of decimal magnitudes. Journal of Applied Developmental Psychology DOI

    Bognar, M., Gyurkovics, M., van Steenbergen, H. & Aczel, B. (2023) Phasic affective signals by themselves do not regulate cognitive control. Cognition and Emotion DOI

    Huang, C., Donk, M. & Theeuwes, J. (2023) Attentional suppression is in place before display onset. Atten Percept Psychophys. DOI

    Salava, A, Salmela, V. (2023) Perceptual learning in dermatology—A Finnish cohort study of undergraduate medical students. J Eur Acad Dermatol Venereol. DOI

    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

    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

    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

    Dijkstra, N., Fleming, S.M. (2023) Subjective signal strength distinguishes reality from imagination. Nat Commun DOI

    Guseva, M., Bogler, C., Allefeld C., Haynes JD. (2023) Instruction effects on randomness in sequence generation. Frontiers in Psychology. DOI

    van Moorselaar, D., & Theeuwes, J. (2023). Statistical Learning Within Objects. Psychological Science DOI

    Lu, Z., van Zoest, W. (2023) Combining social cues in attention: Looking at gaze, head, and pointing cues. Atten Percept Psychophys. DOI

    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

    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

    Reichardt, R., Polner, B., & Simor, P. (2023). Influencing prior knowledge through a short reading impacts curiosity and learning. Applied Cognitive Psychology DOI

    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

    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

    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

    Lee, M.D., Stark, C.E.L. (2023) Bayesian modeling of the Mnemonic Similarity Task using multinomial processing trees. Behaviormetrika DOI

    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

    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

    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

    Zoefel B, Gilbert RA, Davis MH (2023) Intelligibility improves perception of timing changes in speech. PLoS ONE DOI

    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

    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

    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

    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

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys DOI

    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

    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

    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

    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

    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

    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

    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

    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

    Wittmann BC, Şatırer Y. (2022) Decreased associative processing and memory confidence in aphantasia. Learn Mem. DOI

    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

    Mueckstein, M., Heinzel, S., Granacher, U., Brahms, M., Rapp, MA., Stelzel, C. (2022) Modality-specific effects of mental fatigue in multitasking, Acta Psychologica DOI

    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

    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

    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

    Radović T, Rieger T and Manzey D (2022) A global and local perspective of interruption frequency in a visual search task. Front. Psychol. DOI

    Vos, M., Minor, S., & Ramchand, G. C. (2022). Comparing infrared and webcam eye tracking in the Visual World Paradigm. Glossa Psycholinguistics DOI

    Tsang, K. Y., & Mannion, D. J. (2022). Relating Sound and Sight in Simulated Environments. Multisensory Research DOI

    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

    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

    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

    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

    Contemori, G., Saccani, MS., Bonato, M. (2022) Multitasking Effects on Perception and Memory in Older Adults. Vision DOI

    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

    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

    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

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    + \ No newline at end of file diff --git a/Restricting-study-flow.html b/Restricting-study-flow.html index f97b42686..7fe290c63 100644 --- a/Restricting-study-flow.html +++ b/Restricting-study-flow.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Restricting study flow - reloading, linear studies, single-use workers and previews

    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 switch Allow reload.

    GUI Screenshot

    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 switch 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 switch Linear study flow.

    Study Properties Screenshot

    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 and about study links.

    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

    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.

    - +
    Skip to main content
    Version: 3.9.x

    Restricting study flow - reloading, linear studies, single-use workers and previews

    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 switch Allow reload.

    GUI Screenshot

    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 switch 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 switch Linear study flow.

    Study Properties Screenshot

    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 and about study links.

    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

    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.

    + \ No newline at end of file diff --git a/Run-an-experiment-with-JATOS-Workflow.html b/Run-an-experiment-with-JATOS-Workflow.html index 1c665b0d1..615fc8177 100644 --- a/Run-an-experiment-with-JATOS-Workflow.html +++ b/Run-an-experiment-with-JATOS-Workflow.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    Run an experiment with JATOS - Workflow

    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

    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. -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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to add links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    - +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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to add links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    + \ No newline at end of file diff --git a/Run-your-Study-with-Study-Links.html b/Run-your-Study-with-Study-Links.html index 5bb7b9e55..5788385c5 100644 --- a/Run-your-Study-with-Study-Links.html +++ b/Run-your-Study-with-Study-Links.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Run your study with study links

    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

    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

    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 add 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.

    Study Links page screenshot

    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

    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.

    Study Links page screenshot

    Personal type links can be either "Single" or "Multiple". You can find more details about them in the Worker Types 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 add and manage the study links of this type.

    Study Links page screenshot

    1. This button adds one study link without a comment. This button is a shortcut to the "New Study Links" button.
    2. Lets you add 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 add Personal type study links in bulk by changing the Amount value.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. Use this switch 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).
    6. 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

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and add study links is described in its own page: Connect to Mechanical Turk.

    Study Entry page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    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

    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 X/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

    The advantage of using the Study Entry page with the study codes is similar to a 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 add 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

    You can deactivate or activate a batch by clicking on the switch 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

    • 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. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    - +
    Skip to main content
    Version: 3.9.x

    Run your study with study links

    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

    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

    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 add 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.

    Study Links page screenshot

    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

    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.

    Study Links page screenshot

    Personal type links can be either "Single" or "Multiple". You can find more details about them in the Worker Types 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 add and manage the study links of this type.

    Study Links page screenshot

    1. This button adds one study link without a comment. This button is a shortcut to the "New Study Links" button.
    2. Lets you add 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 add Personal type study links in bulk by changing the Amount value.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. Use this switch 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).
    6. 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

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and add study links is described in its own page: Connect to Mechanical Turk.

    Study Entry page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    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

    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 X/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

    The advantage of using the Study Entry page with the study codes is similar to a 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 add 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

    You can deactivate or activate a batch by clicking on the switch 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

    • 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. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    + \ No newline at end of file diff --git a/Session-Data-Three-Types.html b/Session-Data-Three-Types.html index 323aacd8d..2dcd2b188 100644 --- a/Session-Data-Three-Types.html +++ b/Session-Data-Three-Types.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    Session data - Three types

    When to use the sessions?​

    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 SessionGroup SessionStudy Session
    Scope (accesible by)All workers in a batchAll workers in a groupAll components in a study
    UsageExchange and store data relevant for all members of a batchExchange and temporarily store data relevant for all members of a groupExchange 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 batchStore choices of the two members of a Prisoner's Dilemma gamePass on correct answers between components; Keep track of the number of iterations of a given component that is repeated
    LifetimeSurvives after all workers finished their studiesAutomatically deleted once the group is finishedDeleted once the worker finished the study - Hence temporary
    Updated when and viaAny time you call one of the jatos.batchSession functionsAny time you call one of the jatos.groupSession functionsAt the end of each component or if you call jatos.setStudySessionData
    Visible and editable from JATOS' GUIyesyesno
    Requires WebSocketsyesyesno
    Included in exported studiesnonono

    Example Study​

    We have an example study, 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".

    2. Run the study once: easiest is as a JATOS worker (just click 'Run' on the study bar, not on any of the component bars).

    3. 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

    4. 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

    5. 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. 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 -Second component screenshot

    - +Second component screenshot

    + \ No newline at end of file diff --git a/Study-Log.html b/Study-Log.html index f773bb099..07758cb8a 100644 --- a/Study-Log.html +++ b/Study-Log.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Study log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    - +
    Skip to main content
    Version: 3.9.x

    Study log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    + \ No newline at end of file diff --git a/Submit-and-upload-data-to-the-server.html b/Submit-and-upload-data-to-the-server.html index f33b02542..2a8fd758b 100644 --- a/Submit-and-upload-data-to-the-server.html +++ b/Submit-and-upload-data-to-the-server.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    - +
    Skip to main content
    Version: 3.9.x

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    + \ No newline at end of file diff --git a/Support-us.html b/Support-us.html index 3f7d4b8c7..f930bdd9f 100644 --- a/Support-us.html +++ b/Support-us.html @@ -10,13 +10,13 @@ - +
    Skip to main content
    - + \ No newline at end of file diff --git a/Tips-and-Tricks.html b/Tips-and-Tricks.html index 75787dd96..2119e8c60 100644 --- a/Tips-and-Tricks.html +++ b/Tips-and-Tricks.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Tips & tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 add another Personal Single Link and hand it to the worker. But there is another way without adding 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 artificially throttle the network speed in Firefox's and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    Problem: The study runs fine, but as soon as one distributes links for Personal Single or General Single runs via social networks like X/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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    - +
    Skip to main content
    Version: 3.9.x

    Tips & tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 add another Personal Single Link and hand it to the worker. But there is another way without adding 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 artificially throttle the network speed in Firefox's and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    Problem: The study runs fine, but as soon as one distributes links for Personal Single or General Single runs via social networks like X/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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    + \ No newline at end of file diff --git a/Troubleshooting.html b/Troubleshooting.html index 1754d46c9..e72860280 100644 --- a/Troubleshooting.html +++ b/Troubleshooting.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    - +
    Skip to main content
    Version: 3.9.x

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    + \ No newline at end of file diff --git a/Update-JATOS.html b/Update-JATOS.html index 883570662..1e9ff5ca2 100644 --- a/Update-JATOS.html +++ b/Update-JATOS.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    Update JATOS

    We'll periodically update JATOS with new features and bug fixes. We recommend you stay up to date with the latest release. 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:

    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

      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.

    2. 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

    3. After download is complete, you will be asked again for confirmation.

      Update notification Schreenshot

    4. 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.

    5. 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 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.
    2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
    3. Stop the old JATOS and start the new JATOS.
    4. 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
    2. All your studies' and components' properties
    3. The properties of the first (Default) batch

    What will be lost:

    1. All result data and files will be lost
    2. All workers in all batches (including Default batch)
    3. All batches other than the Default batch
    4. Any configuration you did in jatos.conf
    5. 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.
    2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
    3. 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.
    4. Start the new JATOS.

    What will be transferred:

    1. All study assets
    2. All your study and component properties
    3. All batches, together with their workers, and generated study links
    4. All result data and files
    5. All study logs
    6. All logs
    7. JATOS' configuration (as long as it is done in the configuration file)

    What will be lost: -nothing

    - +nothing

    + \ No newline at end of file diff --git a/Use-Prolific.html b/Use-Prolific.html index 789e2ef65..2f8b89949 100644 --- a/Use-Prolific.html +++ b/Use-Prolific.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Use Prolific

    It is very easy to use JATOS together with Prolific 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.

    Here is a screenshot of how it looks in Prolific:

    Prolific screenshot

    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).

    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

    And copy it into the End Redirect URL field of your Study Properties in JATOS:

    screenshot

    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.

    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 in the JavaScript of your last component

    E.g. but change this URL to the one you see in Prolific

    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    You can combine it with sending result data

    var resultData = {id: 123, data: "my important result data"};
    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    - +
    Skip to main content
    Version: 3.9.x

    Use Prolific

    It is very easy to use JATOS together with Prolific 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.

    Here is a screenshot of how it looks in Prolific:

    Prolific screenshot

    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).

    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

    And copy it into the End Redirect URL field of your Study Properties in JATOS:

    screenshot

    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.

    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 in the JavaScript of your last component

    E.g. but change this URL to the one you see in Prolific

    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    You can combine it with sending result data

    var resultData = {id: 123, data: "my important result data"};
    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    + \ No newline at end of file diff --git a/User-Manager.html b/User-Manager.html index 3885e3df5..eb3cc297f 100644 --- a/User-Manager.html +++ b/User-Manager.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Manage JATOS users

    Each experimenter with access to the JATOS server (though the GUI) is a JATOS User. Users can add, 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 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 add 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

    A user can be deactivated (and activated again) by clicking the switch 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

    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.

    Once LDAP is enabled, there will be an additional switch 'LDAP' on the overlay dialog when an admin adds 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 adds LDAP users automatically - they must be added 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 added in JATOS. This means a 'Google' user cannot be added by a JATOS Admin.

    Authentication via OpenId Connect (OIDC)​

    Since version 3.8.5 JATOS users can be authenticated by OIDC. 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). You can find more about how to configure JATOS to use OIDC in the JATOS configuration page.

    If a new user authenticates the first time with OIDC the user will be automatically added in JATOS. This means an OIDC user cannot be added by a JATOS Admin.

    Authentication via ORCID (orcid.org)​

    Since version 3.8.5 JATOS users can be authenticated by ORCID sign-in. 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 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.

    If a new user authenticates the first time with ORCID the user will be automatically added in JATOS. This means an ORCID user cannot be added by a JATOS Admin.

    - +
    Skip to main content
    Version: 3.9.x

    Manage JATOS users

    Each experimenter with access to the JATOS server (though the GUI) is a JATOS User. Users can add, 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 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 add 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

    A user can be deactivated (and activated again) by clicking the switch 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

    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.

    Once LDAP is enabled, there will be an additional switch 'LDAP' on the overlay dialog when an admin adds 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 adds LDAP users automatically - they must be added 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 added in JATOS. This means a 'Google' user cannot be added by a JATOS Admin.

    Authentication via OpenId Connect (OIDC)​

    Since version 3.8.5 JATOS users can be authenticated by OIDC. 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). You can find more about how to configure JATOS to use OIDC in the JATOS configuration page.

    If a new user authenticates the first time with OIDC the user will be automatically added in JATOS. This means an OIDC user cannot be added by a JATOS Admin.

    Authentication via ORCID (orcid.org)​

    Since version 3.8.5 JATOS users can be authenticated by ORCID sign-in. 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 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.

    If a new user authenticates the first time with ORCID the user will be automatically added in JATOS. This means an ORCID user cannot be added by a JATOS Admin.

    + \ No newline at end of file diff --git a/Whats-JATOS.html b/Whats-JATOS.html index ac79f0821..4fe9d9aed 100644 --- a/Whats-JATOS.html +++ b/Whats-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 200 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    - +
    Skip to main content
    Version: 3.9.x

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 200 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    + \ No newline at end of file diff --git a/Worker-Types.html b/Worker-Types.html index fed708546..0af91a287 100644 --- a/Worker-Types.html +++ b/Worker-Types.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Worker and study link types

    Overview​

    Following Amazon Mechanical Turk’s terminology, a worker in JATOS is a person who runs a study (also called participant). JATOS has different worker types and different worker types access a study in different ways. For example, some worker types can run the same study multiple times, whereas others can do it only once.

    A study link is basically the URL that you hand out to a worker. A worker is always assoziated to a study link and share the same type naming. Also read Run your study with study links to get more information about study links.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Typical useDuring study developmentSmall targeted group - each one of them gets their own study linkSmall targeted group of workers who pilot the study or need to do it multiple times - each one of them gets their own study linkBigger groups but with less control - link is shared e.g. via social mediaBigger groups and where the workers need to do the study multiple times - link is shared e.g. via social mediaFor Amazon Mechanical Turk
    Repeat the same study with the same study 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
    Possible bulk creation
    Run group studies

    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.

    With a Personal Single study link a study can be run only once (*But see 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

    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

    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). 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 X/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.

    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 and MTurk Sandbox​

    MTurk and MTurk Sandbox workers access a JATOS study through a study link in Amazon's Mechanical Turk (MTurk).

    More about MTurk study links

    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 page for more details on this.

    - +
    Skip to main content
    Version: 3.9.x

    Worker and study link types

    Overview​

    Following Amazon Mechanical Turk’s terminology, a worker in JATOS is a person who runs a study (also called participant). JATOS has different worker types and different worker types access a study in different ways. For example, some worker types can run the same study multiple times, whereas others can do it only once.

    A study link is basically the URL that you hand out to a worker. A worker is always assoziated to a study link and share the same type naming. Also read Run your study with study links to get more information about study links.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Typical useDuring study developmentSmall targeted group - each one of them gets their own study linkSmall targeted group of workers who pilot the study or need to do it multiple times - each one of them gets their own study linkBigger groups but with less control - link is shared e.g. via social mediaBigger groups and where the workers need to do the study multiple times - link is shared e.g. via social mediaFor Amazon Mechanical Turk
    Repeat the same study with the same study 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
    Possible bulk creation
    Run group studies

    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.

    With a Personal Single study link a study can be run only once (*But see 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

    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

    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). 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 X/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.

    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 and MTurk Sandbox​

    MTurk and MTurk Sandbox workers access a JATOS study through a study link in Amazon's Mechanical Turk (MTurk).

    More about MTurk study links

    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 page for more details on this.

    + \ No newline at end of file diff --git a/Write-Group-Studies-I-Setup.html b/Write-Group-Studies-I-Setup.html index a924cc627..76a17f319 100644 --- a/Write-Group-Studies-I-Setup.html +++ b/Write-Group-Studies-I-Setup.html @@ -10,13 +10,13 @@ - +
    -
    Skip to main content
    Version: 3.9.x

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study switch in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 add two Personal Single study links (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 add a second batch with two other workers.

    Prisoners example

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 add 6 Personal Single study links (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 add one study link type General Single (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    - +
    Skip to main content
    Version: 3.9.x

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study switch in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 add two Personal Single study links (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 add a second batch with two other workers.

    Prisoners example

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 add 6 Personal Single study links (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 add one study link type General Single (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    + \ No newline at end of file diff --git a/Write-Group-Studies-II-JavaScript-and-Messaging.html b/Write-Group-Studies-II-JavaScript-and-Messaging.html index 81589149e..115687f37 100644 --- a/Write-Group-Studies-II-JavaScript-and-Messaging.html +++ b/Write-Group-Studies-II-JavaScript-and-Messaging.html @@ -10,15 +10,15 @@ - +
    Skip to main content
    Version: 3.9.x

    Write Group Studies II - JavaScript and Messaging

    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:

    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 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.

    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.

    Reassigning to a different group​

    To move a worker from one group to a different one, use jatos.reassignGroup. 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 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. Alternatively you can fix a group in JATOS' GUI, in the -Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    - +Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    + \ No newline at end of file diff --git a/Write-your-own-Study-Basics-and-Beyond.html b/Write-your-own-Study-Basics-and-Beyond.html index 5b9993a75..80c6e10c4 100644 --- a/Write-your-own-Study-Basics-and-Beyond.html +++ b/Write-your-own-Study-Basics-and-Beyond.html @@ -10,14 +10,14 @@ - +
    Skip to main content
    Version: 3.9.x

    Write your own study - Basics and beyond

    After you added a new study ... what comes next?

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    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

    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

    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

    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

    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>
        <head>
          <script src="jatos.js"></script>
        </head>
      </html>

    2. 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.

      <script>
        jatos.onLoad(function() {
          // Start here with your code that uses jatos.js' variables and functions
        });
      </script>

    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.

    jatos.js Reference​

    In your JavaScript you will use jatos.js to handle everything JATOS related and in its reference every function and field is described in detail.

    Study/component/batch 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", "component input", or "batch input" (in older JATOS versions they are called "Study JSON Input", "Component JSON Input", or "Batch JSON Input") because both can be easily edited in the study/component/batch properties.

    Study properties / study input

    The input fields take JSON and the data you put in there is then available in your study's JavaScript via jatos.studyJsonInput, jatos.componentJsonInput, and jatos.batchJsonInput.

    The difference between study input, component input and batch input is where they are available in the code of your study. The study input data are available everywhere in your study code, the component input only in the code of this component, and the batch input in all study runs that belong to this batch. There is also a difference in what gets exported with the study: only the study and component input data get exported - not the batch input data.

    Study inputComponent inputBatch input
    Availabilityin the whole study (all components, all batches)only in the component where it was defined (but in all batches)only in the batch that belongs to the study run (but there in all components)
    Exported with the studyyesyesno

    Example:

    If you put the following in the study input of your study properties

    {
      "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.

    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, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    - +To get an idea it's best to start with examples, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    + \ No newline at end of file diff --git a/assets/js/006edb38.2dc6cd2b.js b/assets/js/006edb38.2dc6cd2b.js new file mode 100644 index 000000000..e3eaf1139 --- /dev/null +++ b/assets/js/006edb38.2dc6cd2b.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[6594],{3905:(e,a,t)=>{t.d(a,{Zo:()=>m,kt:()=>c});var n=t(67294);function r(e,a,t){return a in e?Object.defineProperty(e,a,{value:t,enumerable:!0,configurable:!0,writable:!0}):e[a]=t,e}function o(e,a){var t=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);a&&(n=n.filter((function(a){return Object.getOwnPropertyDescriptor(e,a).enumerable}))),t.push.apply(t,n)}return t}function i(e){for(var a=1;a=0||(r[t]=e[t]);return r}(e,a);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,t)&&(r[t]=e[t])}return r}var s=n.createContext({}),p=function(e){var a=n.useContext(s),t=a;return e&&(t="function"==typeof e?e(a):i(i({},a),e)),t},m=function(e){var a=p(e.components);return n.createElement(s.Provider,{value:a},e.children)},d={inlineCode:"code",wrapper:function(e){var a=e.children;return n.createElement(n.Fragment,{},a)}},u=n.forwardRef((function(e,a){var t=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,m=l(e,["components","mdxType","originalType","parentName"]),u=p(t),c=r,h=u["".concat(s,".").concat(c)]||u[c]||d[c]||o;return t?n.createElement(h,i(i({ref:a},m),{},{components:t})):n.createElement(h,i({ref:a},m))}));function c(e,a){var t=arguments,r=a&&a.mdxType;if("string"==typeof e||r){var o=t.length,i=new Array(o);i[0]=u;var l={};for(var s in a)hasOwnProperty.call(a,s)&&(l[s]=a[s]);l.originalType=e,l.mdxType="string"==typeof e?e:r,i[1]=l;for(var p=2;p{t.r(a),t.d(a,{assets:()=>s,contentTitle:()=>i,default:()=>d,frontMatter:()=>o,metadata:()=>l,toc:()=>p});var n=t(83117),r=(t(67294),t(3905));const o={title:"JATOS with MySQL",slug:"/JATOS-with-MySQL.html",sidebar_position:7},i=void 0,l={unversionedId:"Serving_the_Internet/JATOS-with-MySQL",id:"Serving_the_Internet/JATOS-with-MySQL",title:"JATOS with MySQL",description:"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.",source:"@site/docs/Serving_the_Internet/JATOS-with-MySQL.md",sourceDirName:"Serving_the_Internet",slug:"/JATOS-with-MySQL.html",permalink:"/next/JATOS-with-MySQL.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/docs/Serving_the_Internet/JATOS-with-MySQL.md",tags:[],version:"current",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:7,frontMatter:{title:"JATOS with MySQL",slug:"/JATOS-with-MySQL.html",sidebar_position:7},sidebar:"tutorialSidebar",previous:{title:"JATOS on AWS",permalink:"/next/JATOS-in-Amazons-Cloud-without-Docker.html"},next:{title:"Install JATOS via Docker",permalink:"/next/Install-JATOS-via-Docker.html"}},s={},p=[{value:"Installation",id:"installation",level:2},{value:"Configure JATOS",id:"configure-jatos",level:2},{value:"Optional - Deactivate the binary log of your MySQL/MariaDB",id:"optional---deactivate-the-binary-log-of-your-mysqlmariadb",level:2},{value:"Optional - Increase max_allowed_packet size in older MySQL/MariaDB databases",id:"optional---increase-max_allowed_packet-size-in-older-mysqlmariadb-databases",level:2}],m={toc:p};function d(e){let{components:a,...t}=e;return(0,r.kt)("wrapper",(0,n.Z)({},m,t,{components:a,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"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."),(0,r.kt)("p",null,"Possible scenarios why one would use an external database are"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"your JATOS will be used by more than a few users (e.g. several research groups or an institute-wide installation)"),(0,r.kt)("li",{parentName:"ul"},"your JATOS will run studies with many participants"),(0,r.kt)("li",{parentName:"ul"},"the expected traffic is rather high (the studies produce a lot of result data)"),(0,r.kt)("li",{parentName:"ul"},"you want to be able to do a regular database backup (with the embedded H2 database this would involve stopping JATOS)"),(0,r.kt)("li",{parentName:"ul"},"higher trust in the reliability of MySQL/MariaDB")),(0,r.kt)("h2",{id:"installation"},"Installation"),(0,r.kt)("p",null,"One could install the external database on the same machine as JATOS is running or on an extra machine depending on ones need."),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"JATOS requires MySQL >= 5.7 (8.x is fine). JATOS was tested with MariaDB 10.9.7 (other versions likely work too).")),(0,r.kt)("p",null,"There are many manuals out there, e.g. ",(0,r.kt)("a",{parentName:"p",href:"https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-22-04"},"this one"),". One way to set up MySQL:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Install MySQL"),(0,r.kt)("p",{parentName:"li"},"E.g. on Ubuntu"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"sudo apt install mysql-server\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Log in to MySQL's command line terminal:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"mysql -u root -p\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Create a database for JATOS:"),(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Character set and collation are important - otherwise you won't have full UTF-8 support")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Create a user for JATOS: "),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword';\n")),(0,r.kt)("p",{parentName:"li"},"Remember your username and password. You need them when configuring JATOS later on."),(0,r.kt)("p",{parentName:"li"},"Leave out the ",(0,r.kt)("inlineCode",{parentName:"p"},"@'localhost'")," part if the database is not on the same host.")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Grant privileges to the new user:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"You can test the new user: log out of MySQL with ",(0,r.kt)("inlineCode",{parentName:"p"},"exit")," and back in with the newly created user:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"mysql -u jatosuser -p\n")))),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Appart from giving JATOS access to the database it is not necessary to create any tables - JATOS is doing this automatically.")),(0,r.kt)("p",null,"Now you have to configure JATOS to use your MySQL/MariaDB."),(0,r.kt)("h2",{id:"configure-jatos"},"Configure JATOS"),(0,r.kt)("p",null,"There are three ways to set up JATOS to work with a MySQL/MariaDB database."),(0,r.kt)("p",null,"The properties starting with ",(0,r.kt)("inlineCode",{parentName:"p"},"db.default")," are ",(0,r.kt)("strong",{parentName:"p"},"deprecated")," and shouldn't be used anymore. Use ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.db.*")," instead."),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Change IP, port, username and password")," to the ones from your database. The ",(0,r.kt)("em",{parentName:"p"},"driver")," is always ",(0,r.kt)("inlineCode",{parentName:"p"},"com.mysql.cj.jdbc.Driver")," for MySQL or MariaDB."),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Always restart JATOS after making any changes to the configuration (e.g. with ",(0,r.kt)("inlineCode",{parentName:"strong"},"./loader.sh restart"),")")),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via ",(0,r.kt)("strong",{parentName:"p"},"config file")," properties"),(0,r.kt)("p",{parentName:"li"},"The config file, named ",(0,r.kt)("em",{parentName:"p"},"jatos.conf")," or ",(0,r.kt)("em",{parentName:"p"},"production.conf"),", is located in the JATOS folder, in ",(0,r.kt)("em",{parentName:"p"},"./conf")," folder:"),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"in ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.conf")," (JATOS version >= 3.8.3) change the properties ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.db.url"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.db.username"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.db.password"),". The property ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.db.driver")," is always ",(0,r.kt)("inlineCode",{parentName:"p"},"com.mysql.cj.jdbc.Driver"),"."),(0,r.kt)("p",{parentName:"li"}," Example:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},'jatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"\njatos.db.username = "jatosuser"\njatos.db.password = "mypassword"\njatos.db.driver = "com.mysql.cj.jdbc.Driver"\n'))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"in ",(0,r.kt)("inlineCode",{parentName:"p"},"production.conf")," (JATOS version < 3.8.3) change the properties ",(0,r.kt)("inlineCode",{parentName:"p"},"db.default.url"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"db.default.username"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"db.default.password"),". The property ",(0,r.kt)("inlineCode",{parentName:"p"},"db.default.driver")," is always ",(0,r.kt)("inlineCode",{parentName:"p"},"com.mysql.cj.jdbc.Driver"),".")))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via ",(0,r.kt)("strong",{parentName:"p"},"command-line")," arguments"),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"JATOS version >= 3.8.3) set the arguments ",(0,r.kt)("inlineCode",{parentName:"p"},"-Djatos.db.url"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"-Djatos.db.username"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"-Djatos.db.password")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"-Djatos.db.driver")," (always ",(0,r.kt)("inlineCode",{parentName:"p"},"com.mysql.cj.jdbc.Driver"),")."),(0,r.kt)("p",{parentName:"li"}," Example:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},'-Djatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"\n-Djatos.db.username = "jatosuser"\n-Djatos.db.password = "mypassword"\n-Djatos.db.driver = "com.mysql.cj.jdbc.Driver"\n')),(0,r.kt)("p",{parentName:"li"}," and use them together with JATOS start command ",(0,r.kt)("inlineCode",{parentName:"p"},"./loader start"),":"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},'./loader.sh start \\\n -Djatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC" \\\n -Djatos.db.username = "jatosuser" \\\n -Djatos.db.password = "mypassword" \\\n -Djatos.db.driver = "com.mysql.cj.jdbc.Driver"\n'))),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("p",{parentName:"li"},"JATOS version < 3.8.3) set the arguments ",(0,r.kt)("inlineCode",{parentName:"p"},"-Ddb.default.url"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"-Ddb.default.username"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"-Ddb.default.password")," and ",(0,r.kt)("inlineCode",{parentName:"p"},"-Ddb.default.driver")," (always ",(0,r.kt)("inlineCode",{parentName:"p"},"com.mysql.cj.jdbc.Driver"),").")))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via ",(0,r.kt)("strong",{parentName:"p"},"environment")," variables"),(0,r.kt)("p",{parentName:"li"},"Set the variables ",(0,r.kt)("inlineCode",{parentName:"p"},"JATOS_DB_URL"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"JATOS_DB_USERNAME"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"JATOS_DB_PASSWORD"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"JATOS_DB_DRIVER")," (always ",(0,r.kt)("inlineCode",{parentName:"p"},"com.mysql.cj.jdbc.Driver"),")."),(0,r.kt)("p",{parentName:"li"},"Example:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"JATOS_DB_URL=\"jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC\"\nJATOS_DB_USERNAME='jatosuser'\nJATOS_DB_PASSWORD='mypassword'\nJATOS_DB_DRIVER='com.mysql.cj.jdbc.Driver'\n")))),(0,r.kt)("p",null,"You can confirm that JATOS is accessing the correct database by opening JATOS' ",(0,r.kt)("em",{parentName:"p"},"Administration")," page in a browser and then click on ",(0,r.kt)("em",{parentName:"p"},"System Info"),": The field ",(0,r.kt)("em",{parentName:"p"},"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):"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-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\n")),(0,r.kt)("p",null,"Done. Your JATOS uses your MySQL/MariaDB now."),(0,r.kt)("h2",{id:"optional---deactivate-the-binary-log-of-your-mysqlmariadb"},"Optional - Deactivate the binary log of your MySQL/MariaDB"),(0,r.kt)("p",null,"The binary log (also called binlog) serves two purposes: replication and data recovery. More can be found in ",(0,r.kt)("a",{parentName:"p",href:"https://mariadb.com/kb/en/binary-log/"},"MariaDB's documentation"),"."),(0,r.kt)("p",null,"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 ",(0,r.kt)("inlineCode",{parentName:"p"},"/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. "),(0,r.kt)("p",null,"Add ",(0,r.kt)("inlineCode",{parentName:"p"},"skip-log-bin")," to the end of your MySQL/MariaDB config (",(0,r.kt)("a",{parentName:"p",href:"https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#option_mysqld_log-bin"},"details"),"). On many Linux systems the config is in ",(0,r.kt)("inlineCode",{parentName:"p"},"/etc/mysql/mysql.conf.d/mysqld.cnf"),"."),(0,r.kt)("p",null,"The part of your ",(0,r.kt)("em",{parentName:"p"},"mysqld.cnf")," that configures the binary logs could then look similar to this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"# The following can be used as easy to replay backup logs or for replication.\n# note: if you are setting up a replication slave, see README.Debian about\n# other settings you may need to change.\n# server-id = 1\n# log_bin = /var/log/mysql/mysql-bin.log\n# binlog_expire_logs_seconds = 2592000\n# max_binlog_size = 100M\n# binlog_do_db = include_database_name\n# binlog_ignore_db = include_database_name\nskip-log-bin\n")),(0,r.kt)("p",null,"You have to restart MySQL/MariaDB for the changes to take effect."),(0,r.kt)("h2",{id:"optional---increase-max_allowed_packet-size-in-older-mysqlmariadb-databases"},"Optional - Increase ",(0,r.kt)("em",{parentName:"h2"},"max_allowed_packet")," size in older MySQL/MariaDB databases"),(0,r.kt)("p",null,"If you have an older MySQL (< 8.x.x) and your experiments will have large result data you might want to increase the ",(0,r.kt)("em",{parentName:"p"},(0,r.kt)("a",{parentName:"em",href:"https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet"},"max_allowed_packet"))," size. If your result data is larger than the ",(0,r.kt)("em",{parentName:"p"},"max_allowed_packet")," JATOS will just return an 'internal server error'. In JATOS' log in will look similar to this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"[ERROR] - g.ErrorHandler - Internal JATOS error\n[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.\n[WARN] - o.h.e.j.s.SqlExceptionHelper - SQL Error: 0, SQLState: S1000\n")),(0,r.kt)("p",null,"In MySQL, from 8.x.x on, the ",(0,r.kt)("em",{parentName:"p"},"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. "),(0,r.kt)("p",null,"To increase the ",(0,r.kt)("em",{parentName:"p"},"max_allowed_packet")," size just add it to the end of your MySQL/MariaDB config. On many Linux systems the config is in ",(0,r.kt)("inlineCode",{parentName:"p"},"/etc/mysql/mysql.conf.d/mysqld.cnf"),". E.g. to set it to 64MB:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"max_allowed_packet=64M\n")),(0,r.kt)("p",null,"You have to restart the database for the changes to take effect."))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/00c7ad5d.47f29aad.js b/assets/js/00c7ad5d.47f29aad.js new file mode 100644 index 000000000..1d4495043 --- /dev/null +++ b/assets/js/00c7ad5d.47f29aad.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[3601],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>d});var o=n(67294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function i(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=o.createContext({}),m=function(e){var t=o.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},p=function(e){var t=m(e.components);return o.createElement(s.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},u=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,a=e.originalType,s=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=m(n),d=r,h=u["".concat(s,".").concat(d)]||u[d]||c[d]||a;return n?o.createElement(h,i(i({ref:t},p),{},{components:n})):o.createElement(h,i({ref:t},p))}));function d(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var a=n.length,i=new Array(a);i[0]=u;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:r,i[1]=l;for(var m=2;m{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>c,frontMatter:()=>a,metadata:()=>l,toc:()=>m});var o=n(83117),r=(n(67294),n(3905));const a={title:"Customize JATOS' Home Page",slug:"/Customize-JATOS-Home-Page.html",sidebar_position:11},i=void 0,l={unversionedId:"Serving_the_Internet/Customize-JATOS-Home-Page",id:"version-3.6.1/Serving_the_Internet/Customize-JATOS-Home-Page",title:"Customize JATOS' Home Page",description:"Link to Terms of Use (since JATOS v3.5.9)",source:"@site/versioned_docs/version-3.6.1/Serving_the_Internet/Customize-JATOS-Home-Page.md",sourceDirName:"Serving_the_Internet",slug:"/Customize-JATOS-Home-Page.html",permalink:"/3.6.x/Customize-JATOS-Home-Page.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.6.1/Serving_the_Internet/Customize-JATOS-Home-Page.md",tags:[],version:"3.6.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:11,frontMatter:{title:"Customize JATOS' Home Page",slug:"/Customize-JATOS-Home-Page.html",sidebar_position:11},sidebar:"version-3.6.1/tutorialSidebar",previous:{title:"Updating a JATOS server installation",permalink:"/3.6.x/Updating-a-JATOS-server-installation.html"},next:{title:"Install JATOS via Docker",permalink:"/3.6.x/Install-JATOS-via-Docker.html"}},s={},m=[{value:"Link to Terms of Use (since JATOS v3.5.9)",id:"link-to-terms-of-use-since-jatos-v359",level:2},{value:"Welcome Block (since JATOS v3.5.9)",id:"welcome-block-since-jatos-v359",level:2},{value:"With GitHub",id:"with-github",level:3}],p={toc:m};function c(e){let{components:t,...a}=e;return(0,r.kt)("wrapper",(0,o.Z)({},p,a,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h2",{id:"link-to-terms-of-use-since-jatos-v359"},"Link to Terms of Use (since JATOS v3.5.9)"),(0,r.kt)("p",null,"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. "),(0,r.kt)("p",null,"In your JATOS installation folder edit ",(0,r.kt)("inlineCode",{parentName:"p"},"conf/production.conf")," and add the URL under ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.termsOfUseUrl"),". If left empty the info box is not shown."),(0,r.kt)("h2",{id:"welcome-block-since-jatos-v359"},"Welcome Block (since JATOS v3.5.9)"),(0,r.kt)("p",null,"You can customize JATOS' home page to e.g."),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"show your university's logo,"),(0,r.kt)("li",{parentName:"ul"},"add some introduction text, or"),(0,r.kt)("li",{parentName:"ul"},"announce an upcoming event. ")),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"template customized home page",src:n(7818).Z,width:"1919",height:"719"})),(0,r.kt)("p",null,"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."),(0,r.kt)("p",null,"Have a look at this ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/JATOS/customized-home-page-template/blob/main/foobar-university-welcome.html"},"example welcome block"),"."),(0,r.kt)("p",null,"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 ",(0,r.kt)("strong",{parentName:"p"},"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."),(0,r.kt)("p",null,"This welcome block can be fetched from ",(0,r.kt)("strong",{parentName:"p"},"any HTTP server")," that is able to serve HTML. One way is to do it via GitHub."),(0,r.kt)("h3",{id:"with-github"},"With GitHub"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Go to ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/JATOS/customized-home-page-template"},"https://github.com/JATOS/customized-home-page-template"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Click 'Use this template' button to create a copy of this repository")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Change the content of ",(0,r.kt)("inlineCode",{parentName:"p"},"foobar-university-welcome.html")," to your needs")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Add necessary files (e.g. logo images) to your repository")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Configure JATOS: In your JATOS installation folder edit ",(0,r.kt)("inlineCode",{parentName:"p"},"conf/production.conf")," - add ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.brandingUrl"),":"),(0,r.kt)("ol",{parentName:"li"},(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Easy but with rate limit"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},'jatos.brandingUrl = "https://raw.githubusercontent.com/my-user/my-repo/main/foobar-university-welcome.html"\n')),(0,r.kt)("p",{parentName:"li"},"Remember to change ",(0,r.kt)("inlineCode",{parentName:"p"},"my-user"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"my-repo"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"foobar-university-welcome.html"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Better use ",(0,r.kt)("a",{parentName:"p",href:"https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site"},"GitHub pages")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},'jatos.brandingUrl = "https://my-user.github.io/my-repo/foobar-university-welcome.html"\n')),(0,r.kt)("p",{parentName:"li"},"Remember to change ",(0,r.kt)("inlineCode",{parentName:"p"},"my-user"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"my-repo"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"foobar-university-welcome.html"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Restart JATOS"))))}c.isMDXComponent=!0},7818:(e,t,n)=>{n.d(t,{Z:()=>o});const o=n.p+"assets/images/screenshot-branding-6b6e021db43da7b742fbbb7d4775ea52.png"}}]); \ No newline at end of file diff --git a/assets/js/00c7ad5d.9b150e60.js b/assets/js/00c7ad5d.9b150e60.js deleted file mode 100644 index 734c9c1a8..000000000 --- a/assets/js/00c7ad5d.9b150e60.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[3601],{3905:(e,t,n)=>{n.d(t,{Zo:()=>p,kt:()=>d});var o=n(67294);function r(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,o)}return n}function i(e){for(var t=1;t=0||(r[n]=e[n]);return r}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(r[n]=e[n])}return r}var s=o.createContext({}),m=function(e){var t=o.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},p=function(e){var t=m(e.components);return o.createElement(s.Provider,{value:t},e.children)},c={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},u=o.forwardRef((function(e,t){var n=e.components,r=e.mdxType,a=e.originalType,s=e.parentName,p=l(e,["components","mdxType","originalType","parentName"]),u=m(n),d=r,h=u["".concat(s,".").concat(d)]||u[d]||c[d]||a;return n?o.createElement(h,i(i({ref:t},p),{},{components:n})):o.createElement(h,i({ref:t},p))}));function d(e,t){var n=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var a=n.length,i=new Array(a);i[0]=u;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:r,i[1]=l;for(var m=2;m{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>c,frontMatter:()=>a,metadata:()=>l,toc:()=>m});var o=n(83117),r=(n(67294),n(3905));const a={title:"Customize JATOS' Home Page",slug:"/Customize-JATOS-Home-Page.html",sidebar_position:11},i=void 0,l={unversionedId:"Serving_the_Internet/Customize-JATOS-Home-Page",id:"version-3.6.1/Serving_the_Internet/Customize-JATOS-Home-Page",title:"Customize JATOS' Home Page",description:"Link to Terms of Use (since JATOS v3.5.9)",source:"@site/versioned_docs/version-3.6.1/Serving_the_Internet/Customize-JATOS-Home-Page.md",sourceDirName:"Serving_the_Internet",slug:"/Customize-JATOS-Home-Page.html",permalink:"/3.6.x/Customize-JATOS-Home-Page.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.6.1/Serving_the_Internet/Customize-JATOS-Home-Page.md",tags:[],version:"3.6.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:11,frontMatter:{title:"Customize JATOS' Home Page",slug:"/Customize-JATOS-Home-Page.html",sidebar_position:11},sidebar:"version-3.6.1/tutorialSidebar",previous:{title:"Updating a JATOS server installation",permalink:"/3.6.x/Updating-a-JATOS-server-installation.html"},next:{title:"Install JATOS via Docker",permalink:"/3.6.x/Install-JATOS-via-Docker.html"}},s={},m=[{value:"Link to Terms of Use (since JATOS v3.5.9)",id:"link-to-terms-of-use-since-jatos-v359",level:2},{value:"Welcome Block (since JATOS v3.5.9)",id:"welcome-block-since-jatos-v359",level:2},{value:"With GitHub",id:"with-github",level:3}],p={toc:m};function c(e){let{components:t,...a}=e;return(0,r.kt)("wrapper",(0,o.Z)({},p,a,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("h2",{id:"link-to-terms-of-use-since-jatos-v359"},"Link to Terms of Use (since JATOS v3.5.9)"),(0,r.kt)("p",null,"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. "),(0,r.kt)("p",null,"In your JATOS installation folder edit ",(0,r.kt)("inlineCode",{parentName:"p"},"conf/production.conf")," and add the URL under ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.termsOfUseUrl"),". If left empty the info box is not shown."),(0,r.kt)("h2",{id:"welcome-block-since-jatos-v359"},"Welcome Block (since JATOS v3.5.9)"),(0,r.kt)("p",null,"You can customize JATOS' home page to e.g."),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"show your university's logo,"),(0,r.kt)("li",{parentName:"ul"},"add some introduction text, or"),(0,r.kt)("li",{parentName:"ul"},"announce an upcoming event. ")),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"template customized home page",src:n(7818).Z,width:"1919",height:"719"})),(0,r.kt)("p",null,"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."),(0,r.kt)("p",null,"Have a look at this ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/JATOS/customized-home-page-template/blob/main/foobar-university-welcome.html"},"example welcome block"),"."),(0,r.kt)("p",null,"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 ",(0,r.kt)("strong",{parentName:"p"},"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."),(0,r.kt)("p",null,"This welcome block can be fetched from ",(0,r.kt)("strong",{parentName:"p"},"any HTTP server")," that is able to serve HTML. One way is to do it via GitHub."),(0,r.kt)("h3",{id:"with-github"},"With GitHub"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Go to ",(0,r.kt)("a",{parentName:"p",href:"https://github.com/JATOS/customized-home-page-template"},"https://github.com/JATOS/customized-home-page-template"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Click 'Use this template' button to create a copy of this repository")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Change the content of ",(0,r.kt)("inlineCode",{parentName:"p"},"foobar-university-welcome.html")," to your needs")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Add necessary files (e.g. logo images) to your repository")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Configure JATOS: In your JATOS installation folder edit ",(0,r.kt)("inlineCode",{parentName:"p"},"conf/production.conf")," - add ",(0,r.kt)("inlineCode",{parentName:"p"},"jatos.brandingUrl"),":"),(0,r.kt)("ol",{parentName:"li"},(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Easy but with rate limit"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},'jatos.brandingUrl = "https://raw.githubusercontent.com/my-user/my-repo/main/foobar-university-welcome.html"\n')),(0,r.kt)("p",{parentName:"li"},"Remember to change ",(0,r.kt)("inlineCode",{parentName:"p"},"my-user"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"my-repo"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"foobar-university-welcome.html"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Better use ",(0,r.kt)("a",{parentName:"p",href:"https://docs.github.com/en/github/working-with-github-pages/creating-a-github-pages-site"},"GitHub pages")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre"},'jatos.brandingUrl = "https://my-user.github.io/my-repo/foobar-university-welcome.html"\n')),(0,r.kt)("p",{parentName:"li"},"Remember to change ",(0,r.kt)("inlineCode",{parentName:"p"},"my-user"),", ",(0,r.kt)("inlineCode",{parentName:"p"},"my-repo"),", and ",(0,r.kt)("inlineCode",{parentName:"p"},"foobar-university-welcome.html"))))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Restart JATOS"))))}c.isMDXComponent=!0},7818:(e,t,n)=>{n.d(t,{Z:()=>o});const o=n.p+"assets/images/screenshot-branding-6b6e021db43da7b742fbbb7d4775ea52.png"}}]); \ No newline at end of file diff --git a/assets/js/023d77b2.4f1231f0.js b/assets/js/023d77b2.4f1231f0.js new file mode 100644 index 000000000..48da6f433 --- /dev/null +++ b/assets/js/023d77b2.4f1231f0.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[8531],{3905:(e,t,a)=>{a.d(t,{Zo:()=>u,kt:()=>d});var n=a(67294);function r(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function i(e){for(var t=1;t=0||(r[a]=e[a]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var s=n.createContext({}),p=function(e){var t=n.useContext(s),a=t;return e&&(a="function"==typeof e?e(t):i(i({},t),e)),a},u=function(e){var t=p(e.components);return n.createElement(s.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},c=n.forwardRef((function(e,t){var a=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),c=p(a),d=r,y=c["".concat(s,".").concat(d)]||c[d]||m[d]||o;return a?n.createElement(y,i(i({ref:t},u),{},{components:a})):n.createElement(y,i({ref:t},u))}));function d(e,t){var a=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=a.length,i=new Array(o);i[0]=c;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:r,i[1]=l;for(var p=2;p{a.r(t),a.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>m,frontMatter:()=>o,metadata:()=>l,toc:()=>p});var n=a(83117),r=(a(67294),a(3905));const o={title:"JATOS with MySQL",slug:"/JATOS-with-MySQL.html",sidebar_position:7},i=void 0,l={unversionedId:"Serving_the_Internet/JATOS-with-MySQL",id:"version-3.7.1/Serving_the_Internet/JATOS-with-MySQL",title:"JATOS with MySQL",description:"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 database.",source:"@site/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-with-MySQL.md",sourceDirName:"Serving_the_Internet",slug:"/JATOS-with-MySQL.html",permalink:"/3.7.x/JATOS-with-MySQL.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-with-MySQL.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:7,frontMatter:{title:"JATOS with MySQL",slug:"/JATOS-with-MySQL.html",sidebar_position:7},sidebar:"tutorialSidebar",previous:{title:"Configure JATOS on a Server",permalink:"/3.7.x/Configure-JATOS-on-a-Server.html"},next:{title:"Install JATOS via Docker",permalink:"/3.7.x/Install-JATOS-via-Docker.html"}},s={},p=[{value:"Installation",id:"installation",level:2},{value:"Configure JATOS",id:"configure-jatos",level:2},{value:"Optional Deactivate MySQL's binary log",id:"optional-deactivate-mysqls-binary-log",level:2},{value:"Optional Increase 'max_allowed_packet' size in older MySQLs",id:"optional-increase-max_allowed_packet-size-in-older-mysqls",level:2}],u={toc:p};function m(e){let{components:t,...a}=e;return(0,r.kt)("wrapper",(0,n.Z)({},u,a,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"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 database."),(0,r.kt)("p",null,"Possible scenarios why one would use an external database are"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"your JATOS will be used by more than a few users (e.g. several research groups or an institute-wide installation)"),(0,r.kt)("li",{parentName:"ul"},"your JATOS will run studies with many participants"),(0,r.kt)("li",{parentName:"ul"},"the expected traffic is rather high (the studies produce a lot of result data)"),(0,r.kt)("li",{parentName:"ul"},"you want to be able to do a regular database backup (with the embedded H2 database this would involve stopping JATOS)"),(0,r.kt)("li",{parentName:"ul"},"higher trust in the reliability of MySQL (although we had no problems with H2 so far)")),(0,r.kt)("h2",{id:"installation"},"Installation"),(0,r.kt)("p",null,"One could install the external database on the same server as JATOS is running or on an extra server depending on ones need."),(0,r.kt)("p",null,"There are many manuals out there, e.g. ",(0,r.kt)("a",{parentName:"p",href:"https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-20-04"},"this one"),". One way to set up MySQL:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Install MySQL, e.g. on Ubuntu"),(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"JATOS requires MySQL >= 5.7 (8.x is fine)")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"sudo apt install mysql-server\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Log in to MySQL's command line terminal:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"mysql -u root -p\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Create a database for JATOS:"),(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Character set and collation are important - otherwise you won't have full UTF-8 support")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Create a user for JATOS: "),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword';\n")),(0,r.kt)("p",{parentName:"li"},"Remember your username and password. You need them when configuring JATOS later on.")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Grant privileges to the new user:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"You can test the new user: log out of MySQL with ",(0,r.kt)("inlineCode",{parentName:"p"},"exit")," and back in with the newly created user:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"mysql -u jatosuser -p\n")))),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Appart from giving JATOS access to the database it is not necessary to create any tables - JATOS is doing this automatically.")),(0,r.kt)("p",null,"Now you have to configure JATOS to use your MySQL."),(0,r.kt)("h2",{id:"configure-jatos"},"Configure JATOS"),(0,r.kt)("p",null,"There are three ways to set up JATOS to work with a MySQL database. If you are in doubt use 'production.conf'."),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via JATOS config file which is in your JATOS folder in the ",(0,r.kt)("inlineCode",{parentName:"p"},"conf")," folder: ",(0,r.kt)("inlineCode",{parentName:"p"},"conf/production.conf")),(0,r.kt)("p",{parentName:"li"},"Change IP, port, username and password to your needs."),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},'db.default.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"\ndb.default.user="jatosuser"\ndb.default.password="mypassword"\ndb.default.driver=com.mysql.cj.jdbc.Driver\n')),(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Always restart JATOS after making any changes to the configuration (e.g. with ",(0,r.kt)("inlineCode",{parentName:"strong"},"./loader.sh restart"),")"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via command-line arguments:"),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_URL")," - specifies the URL to the database"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_USERNAME")," - set your username"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_PASSWORD")," - set your password"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_DRIVER")," - always ",(0,r.kt)("inlineCode",{parentName:"li"},"com.mysql.cj.jdbc.Driver")," for MySQL")),(0,r.kt)("p",{parentName:"li"},"E.g. to connect to a MySQL running on 127.0.0.1 and port 3306 use (but change username and password):"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-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=sa -DJATOS_DB_PASSWORD=sa -DJATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via environment variables (change IP, port, username and password)"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"export JATOS_DB_URL=\"jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC\"\nexport JATOS_DB_USERNAME=jatosuser\nexport JATOS_DB_PASSWORD='mypassword'\nexport JATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver\n")))),(0,r.kt)("p",null,"You can confirm that JATOS is accessing the correct database by opening JATOS' ",(0,r.kt)("em",{parentName:"p"},"Administration")," page in a browser and then click on ",(0,r.kt)("em",{parentName:"p"},"System Info"),": The field ",(0,r.kt)("em",{parentName:"p"},"DB URL")," should resemble the one from your config."),(0,r.kt)("p",null,"Done. Your JATOS uses your MySQL now."),(0,r.kt)("h2",{id:"optional-deactivate-mysqls-binary-log"},"[Optional]"," Deactivate MySQL's binary log"),(0,r.kt)("p",null,"MySQL's binary logs (also called binlogs) serve two purposes: replication and data recovery. More can be found in ",(0,r.kt)("a",{parentName:"p",href:"https://dev.mysql.com/doc/internals/en/binary-log-overview.html#:~:text=The%20binary%20log%20is%20a,14."},"MySQLs documentation"),"."),(0,r.kt)("p",null,"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's config but on many systems they are under ",(0,r.kt)("inlineCode",{parentName:"p"},"/var/lib/mysql"),". If you have a single MySQL instance (and therefore do not use replication) and you do not need MySQL's data recovery (e.g. have a different backup mechanism) than it is safe to deactivate the binary logs. "),(0,r.kt)("p",null,"Add ",(0,r.kt)("inlineCode",{parentName:"p"},"skip-log-bin")," to the end of your MySQL config (",(0,r.kt)("a",{parentName:"p",href:"https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#option_mysqld_log-bin"},"details"),"). On many Linux systems the config is in ",(0,r.kt)("inlineCode",{parentName:"p"},"/etc/mysql/mysql.conf.d/mysqld.cnf"),"."),(0,r.kt)("p",null,"The part of your 'mysqld.cnf' that configures the binary logs could then look similar to this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"# The following can be used as easy to replay backup logs or for replication.\n# note: if you are setting up a replication slave, see README.Debian about\n# other settings you may need to change.\n# server-id = 1\n# log_bin = /var/log/mysql/mysql-bin.log\n# binlog_expire_logs_seconds = 2592000\n# max_binlog_size = 100M\n# binlog_do_db = include_database_name\n# binlog_ignore_db = include_database_name\nskip-log-bin\n")),(0,r.kt)("p",null,"You have to restart MySQL for the changes to take effect."),(0,r.kt)("h2",{id:"optional-increase-max_allowed_packet-size-in-older-mysqls"},"[Optional]"," Increase 'max_allowed_packet' size in older MySQLs"),(0,r.kt)("p",null,"If you have an older MySQL (< 8.x.x) and your experiments will have large resut data you might want to increase the '",(0,r.kt)("a",{parentName:"p",href:"https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet"},"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:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"[ERROR] - g.ErrorHandler - Internal JATOS error\n[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.\n[WARN] - o.h.e.j.s.SqlExceptionHelper - SQL Error: 0, SQLState: S1000\n")),(0,r.kt)("p",null,"From 8.x.x the 'max_allowed_packet' is by default 64MB and this is usually more than enough. But in version smaller than 8.x.x it is just 4MB by default and before 5.6.6 it's just 1MB. "),(0,r.kt)("p",null,"To increase the 'max_allowed_packet' size just add it to the end of your MySQL config. On many Linux systems the config is in ",(0,r.kt)("inlineCode",{parentName:"p"},"/etc/mysql/mysql.conf.d/mysqld.cnf"),". E.g. to set it to 64MB:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"max_allowed_packet=64M\n")),(0,r.kt)("p",null,"You have to restart MySQL for the changes to take effect."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/023d77b2.eac37b31.js b/assets/js/023d77b2.eac37b31.js deleted file mode 100644 index cb21c912a..000000000 --- a/assets/js/023d77b2.eac37b31.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[8531],{3905:(e,t,a)=>{a.d(t,{Zo:()=>u,kt:()=>d});var n=a(67294);function r(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function o(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function i(e){for(var t=1;t=0||(r[a]=e[a]);return r}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var s=n.createContext({}),p=function(e){var t=n.useContext(s),a=t;return e&&(a="function"==typeof e?e(t):i(i({},t),e)),a},u=function(e){var t=p(e.components);return n.createElement(s.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},c=n.forwardRef((function(e,t){var a=e.components,r=e.mdxType,o=e.originalType,s=e.parentName,u=l(e,["components","mdxType","originalType","parentName"]),c=p(a),d=r,y=c["".concat(s,".").concat(d)]||c[d]||m[d]||o;return a?n.createElement(y,i(i({ref:t},u),{},{components:a})):n.createElement(y,i({ref:t},u))}));function d(e,t){var a=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var o=a.length,i=new Array(o);i[0]=c;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:r,i[1]=l;for(var p=2;p{a.r(t),a.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>m,frontMatter:()=>o,metadata:()=>l,toc:()=>p});var n=a(83117),r=(a(67294),a(3905));const o={title:"JATOS with MySQL",slug:"/JATOS-with-MySQL.html",sidebar_position:7},i=void 0,l={unversionedId:"Serving_the_Internet/JATOS-with-MySQL",id:"version-3.7.1/Serving_the_Internet/JATOS-with-MySQL",title:"JATOS with MySQL",description:"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 database.",source:"@site/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-with-MySQL.md",sourceDirName:"Serving_the_Internet",slug:"/JATOS-with-MySQL.html",permalink:"/3.7.x/JATOS-with-MySQL.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-with-MySQL.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:7,frontMatter:{title:"JATOS with MySQL",slug:"/JATOS-with-MySQL.html",sidebar_position:7},sidebar:"tutorialSidebar",previous:{title:"Configure JATOS on a Server",permalink:"/3.7.x/Configure-JATOS-on-a-Server.html"},next:{title:"Install JATOS via Docker",permalink:"/3.7.x/Install-JATOS-via-Docker.html"}},s={},p=[{value:"Installation",id:"installation",level:2},{value:"Configure JATOS",id:"configure-jatos",level:2},{value:"Optional Deactivate MySQL's binary log",id:"optional-deactivate-mysqls-binary-log",level:2},{value:"Optional Increase 'max_allowed_packet' size in older MySQLs",id:"optional-increase-max_allowed_packet-size-in-older-mysqls",level:2}],u={toc:p};function m(e){let{components:t,...a}=e;return(0,r.kt)("wrapper",(0,n.Z)({},u,a,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"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 database."),(0,r.kt)("p",null,"Possible scenarios why one would use an external database are"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},"your JATOS will be used by more than a few users (e.g. several research groups or an institute-wide installation)"),(0,r.kt)("li",{parentName:"ul"},"your JATOS will run studies with many participants"),(0,r.kt)("li",{parentName:"ul"},"the expected traffic is rather high (the studies produce a lot of result data)"),(0,r.kt)("li",{parentName:"ul"},"you want to be able to do a regular database backup (with the embedded H2 database this would involve stopping JATOS)"),(0,r.kt)("li",{parentName:"ul"},"higher trust in the reliability of MySQL (although we had no problems with H2 so far)")),(0,r.kt)("h2",{id:"installation"},"Installation"),(0,r.kt)("p",null,"One could install the external database on the same server as JATOS is running or on an extra server depending on ones need."),(0,r.kt)("p",null,"There are many manuals out there, e.g. ",(0,r.kt)("a",{parentName:"p",href:"https://www.digitalocean.com/community/tutorials/how-to-install-mysql-on-ubuntu-20-04"},"this one"),". One way to set up MySQL:"),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Install MySQL, e.g. on Ubuntu"),(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"JATOS requires MySQL >= 5.7 (8.x is fine)")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"sudo apt install mysql-server\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Log in to MySQL's command line terminal:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"mysql -u root -p\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Create a database for JATOS:"),(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Character set and collation are important - otherwise you won't have full UTF-8 support")),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Create a user for JATOS: "),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"CREATE USER 'jatosuser'@'localhost' IDENTIFIED BY 'myPassword';\n")),(0,r.kt)("p",{parentName:"li"},"Remember your username and password. You need them when configuring JATOS later on.")),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Grant privileges to the new user:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"You can test the new user: log out of MySQL with ",(0,r.kt)("inlineCode",{parentName:"p"},"exit")," and back in with the newly created user:"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"mysql -u jatosuser -p\n")))),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"Appart from giving JATOS access to the database it is not necessary to create any tables - JATOS is doing this automatically.")),(0,r.kt)("p",null,"Now you have to configure JATOS to use your MySQL."),(0,r.kt)("h2",{id:"configure-jatos"},"Configure JATOS"),(0,r.kt)("p",null,"There are three ways to set up JATOS to work with a MySQL database. If you are in doubt use 'production.conf'."),(0,r.kt)("ol",null,(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via JATOS config file which is in your JATOS folder in the ",(0,r.kt)("inlineCode",{parentName:"p"},"conf")," folder: ",(0,r.kt)("inlineCode",{parentName:"p"},"conf/production.conf")),(0,r.kt)("p",{parentName:"li"},"Change IP, port, username and password to your needs."),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},'db.default.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"\ndb.default.user="jatosuser"\ndb.default.password="mypassword"\ndb.default.driver=com.mysql.cj.jdbc.Driver\n')),(0,r.kt)("p",{parentName:"li"},(0,r.kt)("strong",{parentName:"p"},"Always restart JATOS after making any changes to the configuration (e.g. with ",(0,r.kt)("inlineCode",{parentName:"strong"},"./loader.sh restart"),")"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via command-line arguments:"),(0,r.kt)("ul",{parentName:"li"},(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_URL")," - specifies the URL to the database"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_USERNAME")," - set your username"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_PASSWORD")," - set your password"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("inlineCode",{parentName:"li"},"-DJATOS_DB_DRIVER")," - always ",(0,r.kt)("inlineCode",{parentName:"li"},"com.mysql.cj.jdbc.Driver")," for MySQL")),(0,r.kt)("p",{parentName:"li"},"E.g. to connect to a MySQL running on 127.0.0.1 and port 3306 use (but change username and password):"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-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=sa -DJATOS_DB_PASSWORD=sa -DJATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver\n"))),(0,r.kt)("li",{parentName:"ol"},(0,r.kt)("p",{parentName:"li"},"Via environment variables (change IP, port, username and password)"),(0,r.kt)("pre",{parentName:"li"},(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"export JATOS_DB_URL=\"jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC\"\nexport JATOS_DB_USERNAME=jatosuser\nexport JATOS_DB_PASSWORD='mypassword'\nexport JATOS_DB_DRIVER=com.mysql.cj.jdbc.Driver\n")))),(0,r.kt)("p",null,"You can confirm that JATOS is accessing the correct database by opening JATOS' ",(0,r.kt)("em",{parentName:"p"},"Administration")," page in a browser and then click on ",(0,r.kt)("em",{parentName:"p"},"System Info"),": The field ",(0,r.kt)("em",{parentName:"p"},"DB URL")," should resemble the one from your config."),(0,r.kt)("p",null,"Done. Your JATOS uses your MySQL now."),(0,r.kt)("h2",{id:"optional-deactivate-mysqls-binary-log"},"[Optional]"," Deactivate MySQL's binary log"),(0,r.kt)("p",null,"MySQL's binary logs (also called binlogs) serve two purposes: replication and data recovery. More can be found in ",(0,r.kt)("a",{parentName:"p",href:"https://dev.mysql.com/doc/internals/en/binary-log-overview.html#:~:text=The%20binary%20log%20is%20a,14."},"MySQLs documentation"),"."),(0,r.kt)("p",null,"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's config but on many systems they are under ",(0,r.kt)("inlineCode",{parentName:"p"},"/var/lib/mysql"),". If you have a single MySQL instance (and therefore do not use replication) and you do not need MySQL's data recovery (e.g. have a different backup mechanism) than it is safe to deactivate the binary logs. "),(0,r.kt)("p",null,"Add ",(0,r.kt)("inlineCode",{parentName:"p"},"skip-log-bin")," to the end of your MySQL config (",(0,r.kt)("a",{parentName:"p",href:"https://dev.mysql.com/doc/refman/8.0/en/replication-options-binary-log.html#option_mysqld_log-bin"},"details"),"). On many Linux systems the config is in ",(0,r.kt)("inlineCode",{parentName:"p"},"/etc/mysql/mysql.conf.d/mysqld.cnf"),"."),(0,r.kt)("p",null,"The part of your 'mysqld.cnf' that configures the binary logs could then look similar to this:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"# The following can be used as easy to replay backup logs or for replication.\n# note: if you are setting up a replication slave, see README.Debian about\n# other settings you may need to change.\n# server-id = 1\n# log_bin = /var/log/mysql/mysql-bin.log\n# binlog_expire_logs_seconds = 2592000\n# max_binlog_size = 100M\n# binlog_do_db = include_database_name\n# binlog_ignore_db = include_database_name\nskip-log-bin\n")),(0,r.kt)("p",null,"You have to restart MySQL for the changes to take effect."),(0,r.kt)("h2",{id:"optional-increase-max_allowed_packet-size-in-older-mysqls"},"[Optional]"," Increase 'max_allowed_packet' size in older MySQLs"),(0,r.kt)("p",null,"If you have an older MySQL (< 8.x.x) and your experiments will have large resut data you might want to increase the '",(0,r.kt)("a",{parentName:"p",href:"https://dev.mysql.com/doc/refman/8.0/en/server-system-variables.html#sysvar_max_allowed_packet"},"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:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre"},"[ERROR] - g.ErrorHandler - Internal JATOS error\n[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.\n[WARN] - o.h.e.j.s.SqlExceptionHelper - SQL Error: 0, SQLState: S1000\n")),(0,r.kt)("p",null,"From 8.x.x the 'max_allowed_packet' is by default 64MB and this is usually more than enough. But in version smaller than 8.x.x it is just 4MB by default and before 5.6.6 it's just 1MB. "),(0,r.kt)("p",null,"To increase the 'max_allowed_packet' size just add it to the end of your MySQL config. On many Linux systems the config is in ",(0,r.kt)("inlineCode",{parentName:"p"},"/etc/mysql/mysql.conf.d/mysqld.cnf"),". E.g. to set it to 64MB:"),(0,r.kt)("pre",null,(0,r.kt)("code",{parentName:"pre",className:"language-bash"},"max_allowed_packet=64M\n")),(0,r.kt)("p",null,"You have to restart MySQL for the changes to take effect."))}m.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/026a64b7.9913c1ef.js b/assets/js/026a64b7.9913c1ef.js new file mode 100644 index 000000000..b4af9c135 --- /dev/null +++ b/assets/js/026a64b7.9913c1ef.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[9750],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>h});var r=n(67294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function i(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),u=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},c=function(e){var t=u(e.components);return r.createElement(l.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},d=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=u(n),h=o,m=d["".concat(l,".").concat(h)]||d[h]||p[h]||a;return n?r.createElement(m,i(i({ref:t},c),{},{components:n})):r.createElement(m,i({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var u=2;u{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>i,default:()=>p,frontMatter:()=>a,metadata:()=>s,toc:()=>u});var r=n(83117),o=(n(67294),n(3905));const a={title:"Use MTurk",slug:"/Connect-to-Mechanical-Turk.html",sidebar_position:5},i=void 0,s={unversionedId:"Run_your_study/Connect-to-Mechanical-Turk",id:"version-3.7.1/Run_your_study/Connect-to-Mechanical-Turk",title:"Use MTurk",description:"Use your JATOS study with Mturk is easy, although a fair amount of clicking is required.",source:"@site/versioned_docs/version-3.7.1/Run_your_study/Connect-to-Mechanical-Turk.md",sourceDirName:"Run_your_study",slug:"/Connect-to-Mechanical-Turk.html",permalink:"/3.7.x/Connect-to-Mechanical-Turk.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Run_your_study/Connect-to-Mechanical-Turk.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:5,frontMatter:{title:"Use MTurk",slug:"/Connect-to-Mechanical-Turk.html",sidebar_position:5},sidebar:"tutorialSidebar",previous:{title:"Restricting study flow - reloading, linear studies, single-use workers and previews",permalink:"/3.7.x/Restricting-study-flow.html"},next:{title:"Use Prolific",permalink:"/3.7.x/Use-Prolific.html"}},l={},u=[{value:"You will need",id:"you-will-need",level:3},{value:"On JATOS' side",id:"on-jatos-side",level:3},{value:"On MTurk's page",id:"on-mturks-page",level:3},{value:"What should happen",id:"what-should-happen",level:3},{value:"How to check the confirmation codes",id:"how-to-check-the-confirmation-codes",level:3}],c={toc:u};function p(e){let{components:t,...a}=e;return(0,o.kt)("wrapper",(0,r.Z)({},c,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Use your JATOS study with Mturk is easy, although a fair amount of clicking is required."),(0,o.kt)("p",null,"A good idea is always to try it yourself first in ",(0,o.kt)("a",{parentName:"p",href:"https://requester.mturk.com/developer/sandbox"},"MTurk Sandbox")," before you let real workers do it."),(0,o.kt)("h3",{id:"you-will-need"},"You will need"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"A requester Mturk account"),(0,o.kt)("li",{parentName:"ul"},"Your study running on a ",(0,o.kt)("a",{parentName:"li",href:"Bring-your-JATOS-online.html"},"JATOS server")),(0,o.kt)("li",{parentName:"ul"},"A description of the study (this can be the same as the one you included in the study description within JATOS)")),(0,o.kt)("h3",{id:"on-jatos-side"},"On JATOS' side"),(0,o.kt)("p",null,"In JATOS, go to your study's page and click on the Study Links button and open the batch you want to run."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"JATOS GUI screenshot",src:n(32223).Z,width:"1919",height:"625"})),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Don't forget to enable the MTurk type")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Click on ",(0,o.kt)("em",{parentName:"p"},"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."))),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"JATOS GUI screenshot",src:n(6560).Z,width:"1902",height:"605"})),(0,o.kt)("h3",{id:"on-mturks-page"},"On MTurk's page"),(0,o.kt)("p",null,"You first have to create a project in the MTurk interface:"),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Sign into your ",(0,o.kt)("a",{parentName:"p",href:"https://requester.mturk.com/signin_options"},"MTurk requester account")," (or ",(0,o.kt)("a",{parentName:"p",href:"https://requestersandbox.mturk.com/signin_options"},"requester sandbox account"),")")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Create \u27f6 New Project \u27f6 Survey Link \u27f6 Create Project - or just click this ",(0,o.kt)("a",{parentName:"p",href:"https://requester.mturk.com/create/projects/new"},"link for requester")," (or this ",(0,o.kt)("a",{parentName:"p",href:"https://requestersandbox.mturk.com/create/projects/new"},"link for requester sandbox"),")")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Complete the ",(0,o.kt)("em",{parentName:"p"},"Enter Properties")," tab")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Click on the ",(0,o.kt)("em",{parentName:"p"},"Design layout")," button in the bottom of the page. ")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Click on the ",(0,o.kt)("em",{parentName:"p"},"Source")," button. You'll see some text in an editable window, corresponding to an HTML file. Delete the entire text in this field."),(0,o.kt)("p",{parentName:"li"},(0,o.kt)("img",{alt:"MTurk Schreenshot",src:n(23190).Z,width:"2656",height:"1112"})," ")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"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).")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"To exit the editing mode, click on the \u2018Source\u2019 button again and continue setting up your study in MTurk."),(0,o.kt)("p",{parentName:"li"},(0,o.kt)("img",{alt:"MTurk Schreenshot",src:n(95882).Z,width:"2688",height:"810"})))),(0,o.kt)("h3",{id:"what-should-happen"},"What should happen"),(0,o.kt)("p",null,"When an MTurk worker finishes a study they'll see a confirmation code like this one."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Confirmation code",src:n(28424).Z,width:"1919",height:"251"})),(0,o.kt)("h3",{id:"how-to-check-the-confirmation-codes"},"How to check the confirmation codes"),(0,o.kt)("p",null,"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. "),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Results of Mturk workers",src:n(19083).Z,width:"1919",height:"657"})))}p.isMDXComponent=!0},28424:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/MTurk-confirmation-code_371-2d571d88a347b5e2a675e6f2a2f299f7.png"},95882:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/MTurk-source-editor-done-5e6c5c618f8f72c07d7ee05bfd8fabea.png"},23190:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/MTurk-source-editor-e13233189d2b43732d59913807341303.png"},19083:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/mturk-results-a07adbabc7ad19b5baf368cde4a8398c.png"},32223:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/study_links_mturk-38e9ff32fd88b71f2c97fb14c6cb25f9.png"},6560:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/study_links_mturk_source_code-cbc30940425e9a29f7a78e58ef5e1bb0.png"}}]); \ No newline at end of file diff --git a/assets/js/026a64b7.a0d5c9fb.js b/assets/js/026a64b7.a0d5c9fb.js deleted file mode 100644 index 4422664ca..000000000 --- a/assets/js/026a64b7.a0d5c9fb.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[9750],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>h});var r=n(67294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function a(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function i(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var l=r.createContext({}),u=function(e){var t=r.useContext(l),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},c=function(e){var t=u(e.components);return r.createElement(l.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},d=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,a=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),d=u(n),h=o,m=d["".concat(l,".").concat(h)]||d[h]||p[h]||a;return n?r.createElement(m,i(i({ref:t},c),{},{components:n})):r.createElement(m,i({ref:t},c))}));function h(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var a=n.length,i=new Array(a);i[0]=d;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var u=2;u{n.r(t),n.d(t,{assets:()=>l,contentTitle:()=>i,default:()=>p,frontMatter:()=>a,metadata:()=>s,toc:()=>u});var r=n(83117),o=(n(67294),n(3905));const a={title:"Use MTurk",slug:"/Connect-to-Mechanical-Turk.html",sidebar_position:5},i=void 0,s={unversionedId:"Run_your_study/Connect-to-Mechanical-Turk",id:"version-3.7.1/Run_your_study/Connect-to-Mechanical-Turk",title:"Use MTurk",description:"Use your JATOS study with Mturk is easy, although a fair amount of clicking is required.",source:"@site/versioned_docs/version-3.7.1/Run_your_study/Connect-to-Mechanical-Turk.md",sourceDirName:"Run_your_study",slug:"/Connect-to-Mechanical-Turk.html",permalink:"/3.7.x/Connect-to-Mechanical-Turk.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Run_your_study/Connect-to-Mechanical-Turk.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:5,frontMatter:{title:"Use MTurk",slug:"/Connect-to-Mechanical-Turk.html",sidebar_position:5},sidebar:"tutorialSidebar",previous:{title:"Restricting study flow - reloading, linear studies, single-use workers and previews",permalink:"/3.7.x/Restricting-study-flow.html"},next:{title:"Use Prolific",permalink:"/3.7.x/Use-Prolific.html"}},l={},u=[{value:"You will need",id:"you-will-need",level:3},{value:"On JATOS' side",id:"on-jatos-side",level:3},{value:"On MTurk's page",id:"on-mturks-page",level:3},{value:"What should happen",id:"what-should-happen",level:3},{value:"How to check the confirmation codes",id:"how-to-check-the-confirmation-codes",level:3}],c={toc:u};function p(e){let{components:t,...a}=e;return(0,o.kt)("wrapper",(0,r.Z)({},c,a,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Use your JATOS study with Mturk is easy, although a fair amount of clicking is required."),(0,o.kt)("p",null,"A good idea is always to try it yourself first in ",(0,o.kt)("a",{parentName:"p",href:"https://requester.mturk.com/developer/sandbox"},"MTurk Sandbox")," before you let real workers do it."),(0,o.kt)("h3",{id:"you-will-need"},"You will need"),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},"A requester Mturk account"),(0,o.kt)("li",{parentName:"ul"},"Your study running on a ",(0,o.kt)("a",{parentName:"li",href:"Bring-your-JATOS-online.html"},"JATOS server")),(0,o.kt)("li",{parentName:"ul"},"A description of the study (this can be the same as the one you included in the study description within JATOS)")),(0,o.kt)("h3",{id:"on-jatos-side"},"On JATOS' side"),(0,o.kt)("p",null,"In JATOS, go to your study's page and click on the Study Links button and open the batch you want to run."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"JATOS GUI screenshot",src:n(32223).Z,width:"1919",height:"625"})),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Don't forget to enable the MTurk type")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Click on ",(0,o.kt)("em",{parentName:"p"},"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."))),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"JATOS GUI screenshot",src:n(6560).Z,width:"1902",height:"605"})),(0,o.kt)("h3",{id:"on-mturks-page"},"On MTurk's page"),(0,o.kt)("p",null,"You first have to create a project in the MTurk interface:"),(0,o.kt)("ol",null,(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Sign into your ",(0,o.kt)("a",{parentName:"p",href:"https://requester.mturk.com/signin_options"},"MTurk requester account")," (or ",(0,o.kt)("a",{parentName:"p",href:"https://requestersandbox.mturk.com/signin_options"},"requester sandbox account"),")")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Create \u27f6 New Project \u27f6 Survey Link \u27f6 Create Project - or just click this ",(0,o.kt)("a",{parentName:"p",href:"https://requester.mturk.com/create/projects/new"},"link for requester")," (or this ",(0,o.kt)("a",{parentName:"p",href:"https://requestersandbox.mturk.com/create/projects/new"},"link for requester sandbox"),")")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Complete the ",(0,o.kt)("em",{parentName:"p"},"Enter Properties")," tab")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Click on the ",(0,o.kt)("em",{parentName:"p"},"Design layout")," button in the bottom of the page. ")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"Click on the ",(0,o.kt)("em",{parentName:"p"},"Source")," button. You'll see some text in an editable window, corresponding to an HTML file. Delete the entire text in this field."),(0,o.kt)("p",{parentName:"li"},(0,o.kt)("img",{alt:"MTurk Schreenshot",src:n(23190).Z,width:"2656",height:"1112"})," ")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"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).")),(0,o.kt)("li",{parentName:"ol"},(0,o.kt)("p",{parentName:"li"},"To exit the editing mode, click on the \u2018Source\u2019 button again and continue setting up your study in MTurk."),(0,o.kt)("p",{parentName:"li"},(0,o.kt)("img",{alt:"MTurk Schreenshot",src:n(95882).Z,width:"2688",height:"810"})))),(0,o.kt)("h3",{id:"what-should-happen"},"What should happen"),(0,o.kt)("p",null,"When an MTurk worker finishes a study they'll see a confirmation code like this one."),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Confirmation code",src:n(28424).Z,width:"1919",height:"251"})),(0,o.kt)("h3",{id:"how-to-check-the-confirmation-codes"},"How to check the confirmation codes"),(0,o.kt)("p",null,"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. "),(0,o.kt)("p",null,(0,o.kt)("img",{alt:"Results of Mturk workers",src:n(19083).Z,width:"1919",height:"657"})))}p.isMDXComponent=!0},28424:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/MTurk-confirmation-code_371-2d571d88a347b5e2a675e6f2a2f299f7.png"},95882:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/MTurk-source-editor-done-5e6c5c618f8f72c07d7ee05bfd8fabea.png"},23190:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/MTurk-source-editor-e13233189d2b43732d59913807341303.png"},19083:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/mturk-results-a07adbabc7ad19b5baf368cde4a8398c.png"},32223:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/study_links_mturk-38e9ff32fd88b71f2c97fb14c6cb25f9.png"},6560:(e,t,n)=>{n.d(t,{Z:()=>r});const r=n.p+"assets/images/study_links_mturk_source_code-cbc30940425e9a29f7a78e58ef5e1bb0.png"}}]); \ No newline at end of file diff --git a/assets/js/02c1c4b0.5d873afa.js b/assets/js/02c1c4b0.5d873afa.js new file mode 100644 index 000000000..7c374fc32 --- /dev/null +++ b/assets/js/02c1c4b0.5d873afa.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[3539],{3905:(e,t,n)=>{n.d(t,{Zo:()=>l,kt:()=>m});var r=n(67294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var c=r.createContext({}),p=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},l=function(e){var t=p(e.components);return r.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},u=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,c=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),u=p(n),m=o,h=u["".concat(c,".").concat(m)]||u[m]||d[m]||i;return n?r.createElement(h,a(a({ref:t},l),{},{components:n})):r.createElement(h,a({ref:t},l))}));function m(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=u;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,a[1]=s;for(var p=2;p{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>a,default:()=>d,frontMatter:()=>i,metadata:()=>s,toc:()=>p});var r=n(83117),o=(n(67294),n(3905));const i={title:"JATOS with Nginx",slug:"/JATOS-with-Nginx.html",sidebar_position:11},a=void 0,s={unversionedId:"Serving_the_Internet/JATOS-with-Nginx",id:"version-3.9.1/Serving_the_Internet/JATOS-with-Nginx",title:"JATOS with Nginx",description:"Here is an example for a configuration of Nginx as a reverse proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common.",source:"@site/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md",sourceDirName:"Serving_the_Internet",slug:"/JATOS-with-Nginx.html",permalink:"/JATOS-with-Nginx.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md",tags:[],version:"3.9.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:11,frontMatter:{title:"JATOS with Nginx",slug:"/JATOS-with-Nginx.html",sidebar_position:11},sidebar:"tutorialSidebar",previous:{title:"JATOS in a cluster",permalink:"/JATOS-in-a-cluster.html"},next:{title:"JATOS with Apache",permalink:"/JATOS-with-Apache.html"}},c={},p=[],l={toc:p};function d(e){let{components:t,...n}=e;return(0,o.kt)("wrapper",(0,r.Z)({},l,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Here is an example for a configuration of ",(0,o.kt)("a",{parentName:"p",href:"https://www.nginx.com/"},"Nginx")," as a reverse proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common."),(0,o.kt)("p",null,"A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is ",(0,o.kt)("a",{parentName:"p",href:"https://certbot.eff.org/"},"certbot.eff.org")," from the Electronic Frontier Foundation."),(0,o.kt)("p",null,"The following config is the content of ",(0,o.kt)("inlineCode",{parentName:"p"},"/etc/nginx/nginx.conf"),". Change it to your needs. You probably want to change your servers address (",(0,o.kt)("inlineCode",{parentName:"p"},"www.example.com")," in the example) and the path to the SSL certificate and its key."),(0,o.kt)("p",null,"For JATOS versions 3.8.1 and older it is necessary to set the ",(0,o.kt)("inlineCode",{parentName:"p"},"X-Forwarded-*")," headers with ",(0,o.kt)("inlineCode",{parentName:"p"},"proxy_set_header")," to tell JATOS the original requester's IP address. This is not necessary from 3.8.2 and newer."),(0,o.kt)("p",null,"As an additional security measurement you can uncomment the ",(0,o.kt)("inlineCode",{parentName:"p"},"location /jatos")," and config your local network. This will restrict the access to JATOS' GUI (every URL starting with ",(0,o.kt)("inlineCode",{parentName:"p"},"/jatos"),") to the local network."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"user www-data;\npid /run/nginx.pid;\nworker_processes auto;\nworker_rlimit_nofile 65535;\n\n# Load modules\ninclude /etc/nginx/modules-enabled/*.conf;\n\nevents {\n multi_accept on;\n worker_connections 65535;\n}\n\nhttp {\n sendfile on;\n tcp_nopush on;\n client_max_body_size 500M;\n\n # MIME\n include mime.types;\n default_type application/octet-stream;\n\n # Logging\n access_log off;\n error_log /var/log/nginx/error.log warn;\n\n proxy_buffering off;\n proxy_set_header Host $http_host;\n proxy_http_version 1.1;\n\n # Needed for websockets\n map $http_upgrade $connection_upgrade {\n default upgrade;\n '' close;\n }\n\n # Load configs\n include /etc/nginx/conf.d/*.conf;\n\n upstream jatos-backend {\n server 127.0.0.1:9000;\n }\n\n # Redirect http to https\n server {\n listen 80;\n # --\x3e Change to your domain <--\n server_name www.example.com;\n rewrite ^ https://www.example.com$request_uri? permanent;\n }\n\n server {\n listen 443 ssl http2;\n # --\x3e Change to your domain <--\n server_name www.example.com;\n keepalive_timeout 70;\n\n # Encryption\n # --\x3e Change to your certificate <--\n ssl_certificate /etc/ssl/certs/localhost.crt;\n ssl_certificate_key /etc/ssl/private/localhost.key;\n ssl_protocols TLSv1.2 TLSv1.3;\n\n # WebSocket location (JATOS' group and batch channel and the test page)\n location ~ \"/(jatos/testWebSocket|publix/[a-z0-9-]+/(group/join|batch/open))\" {\n proxy_pass http://jatos-backend;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection $connection_upgrade;\n proxy_connect_timeout 7d; # Keep open for 7 days even without any transmission\n proxy_send_timeout 7d;\n proxy_read_timeout 7d;\n }\n\n # Restrict access to JATOS' GUI to local network, e.g. 192.168.1.*\n # location /jatos {\n # allow 192.168.1.0/24;\n # deny all;\n # proxy_pass http://jatos-backend;\n # proxy_connect_timeout 300;\n # proxy_send_timeout 300;\n # proxy_read_timeout 300;\n # send_timeout 300;\n # }\n\n # All other traffic\n location / {\n proxy_pass http://jatos-backend;\n proxy_connect_timeout 300;\n proxy_send_timeout 300;\n proxy_read_timeout 300;\n send_timeout 300;\n }\n }\n}\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/02c1c4b0.8639d505.js b/assets/js/02c1c4b0.8639d505.js deleted file mode 100644 index 79db8817f..000000000 --- a/assets/js/02c1c4b0.8639d505.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[3539],{3905:(e,t,n)=>{n.d(t,{Zo:()=>l,kt:()=>m});var r=n(67294);function o(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function i(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function a(e){for(var t=1;t=0||(o[n]=e[n]);return o}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(o[n]=e[n])}return o}var c=r.createContext({}),p=function(e){var t=r.useContext(c),n=t;return e&&(n="function"==typeof e?e(t):a(a({},t),e)),n},l=function(e){var t=p(e.components);return r.createElement(c.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},u=r.forwardRef((function(e,t){var n=e.components,o=e.mdxType,i=e.originalType,c=e.parentName,l=s(e,["components","mdxType","originalType","parentName"]),u=p(n),m=o,h=u["".concat(c,".").concat(m)]||u[m]||d[m]||i;return n?r.createElement(h,a(a({ref:t},l),{},{components:n})):r.createElement(h,a({ref:t},l))}));function m(e,t){var n=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var i=n.length,a=new Array(i);a[0]=u;var s={};for(var c in t)hasOwnProperty.call(t,c)&&(s[c]=t[c]);s.originalType=e,s.mdxType="string"==typeof e?e:o,a[1]=s;for(var p=2;p{n.r(t),n.d(t,{assets:()=>c,contentTitle:()=>a,default:()=>d,frontMatter:()=>i,metadata:()=>s,toc:()=>p});var r=n(83117),o=(n(67294),n(3905));const i={title:"JATOS with Nginx",slug:"/JATOS-with-Nginx.html",sidebar_position:11},a=void 0,s={unversionedId:"Serving_the_Internet/JATOS-with-Nginx",id:"version-3.9.1/Serving_the_Internet/JATOS-with-Nginx",title:"JATOS with Nginx",description:"Here is an example for a configuration of Nginx as a reverse proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common.",source:"@site/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md",sourceDirName:"Serving_the_Internet",slug:"/JATOS-with-Nginx.html",permalink:"/JATOS-with-Nginx.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.9.1/Serving_the_Internet/JATOS-with-Nginx.md",tags:[],version:"3.9.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:11,frontMatter:{title:"JATOS with Nginx",slug:"/JATOS-with-Nginx.html",sidebar_position:11},sidebar:"tutorialSidebar",previous:{title:"JATOS in a cluster",permalink:"/JATOS-in-a-cluster.html"},next:{title:"JATOS with Apache",permalink:"/JATOS-with-Apache.html"}},c={},p=[],l={toc:p};function d(e){let{components:t,...n}=e;return(0,o.kt)("wrapper",(0,r.Z)({},l,n,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("p",null,"Here is an example for a configuration of ",(0,o.kt)("a",{parentName:"p",href:"https://www.nginx.com/"},"Nginx")," as a reverse proxy in front of JATOS. It is not necessary to run JATOS with a proxy but it's common."),(0,o.kt)("p",null,"A JATOS server that handles sensitive or private data should always use encryption (HTTPS). A nice free certificate issuer is ",(0,o.kt)("a",{parentName:"p",href:"https://certbot.eff.org/"},"certbot.eff.org")," from the Electronic Frontier Foundation."),(0,o.kt)("p",null,"The following config is the content of ",(0,o.kt)("inlineCode",{parentName:"p"},"/etc/nginx/nginx.conf"),". Change it to your needs. You probably want to change your servers address (",(0,o.kt)("inlineCode",{parentName:"p"},"www.example.com")," in the example) and the path to the SSL certificate and its key."),(0,o.kt)("p",null,"For JATOS versions 3.8.1 and older it is necessary to set the ",(0,o.kt)("inlineCode",{parentName:"p"},"X-Forwarded-*")," headers with ",(0,o.kt)("inlineCode",{parentName:"p"},"proxy_set_header")," to tell JATOS the original requester's IP address. This is not necessary from 3.8.2 and newer."),(0,o.kt)("p",null,"As an additional security measurement you can uncomment the ",(0,o.kt)("inlineCode",{parentName:"p"},"location /jatos")," and config your local network. This will restrict the access to JATOS' GUI (every URL starting with ",(0,o.kt)("inlineCode",{parentName:"p"},"/jatos"),") to the local network."),(0,o.kt)("pre",null,(0,o.kt)("code",{parentName:"pre",className:"language-shell"},"user www-data;\npid /run/nginx.pid;\nworker_processes auto;\nworker_rlimit_nofile 65535;\n\n# Load modules\ninclude /etc/nginx/modules-enabled/*.conf;\n\nevents {\n multi_accept on;\n worker_connections 65535;\n}\n\nhttp {\n sendfile on;\n tcp_nopush on;\n client_max_body_size 500M;\n\n # MIME\n include mime.types;\n default_type application/octet-stream;\n\n # Logging\n access_log off;\n error_log /var/log/nginx/error.log warn;\n\n proxy_buffering off;\n proxy_set_header Host $http_host;\n proxy_http_version 1.1;\n\n # Needed for websockets\n map $http_upgrade $connection_upgrade {\n default upgrade;\n '' close;\n }\n\n # Load configs\n include /etc/nginx/conf.d/*.conf;\n\n upstream jatos-backend {\n server 127.0.0.1:9000;\n }\n\n # Redirect http to https\n server {\n listen 80;\n # --\x3e Change to your domain <--\n server_name www.example.com;\n rewrite ^ https://www.example.com$request_uri? permanent;\n }\n\n server {\n listen 443 ssl http2;\n # --\x3e Change to your domain <--\n server_name www.example.com;\n keepalive_timeout 70;\n\n # Encryption\n # --\x3e Change to your certificate <--\n ssl_certificate /etc/ssl/certs/localhost.crt;\n ssl_certificate_key /etc/ssl/private/localhost.key;\n ssl_protocols TLSv1.2 TLSv1.3;\n\n # WebSocket location (JATOS' group and batch channel and the test page)\n location ~ \"/(jatos/testWebSocket|publix/[a-z0-9-]+/(group/join|batch/open))\" {\n proxy_pass http://jatos-backend;\n proxy_http_version 1.1;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection $connection_upgrade;\n proxy_connect_timeout 7d; # Keep open for 7 days even without any transmission\n proxy_send_timeout 7d;\n proxy_read_timeout 7d;\n }\n\n # Restrict access to JATOS' GUI to local network, e.g. 192.168.1.*\n # location /jatos {\n # allow 192.168.1.0/24;\n # deny all;\n # proxy_pass http://jatos-backend;\n # proxy_connect_timeout 300;\n # proxy_send_timeout 300;\n # proxy_read_timeout 300;\n # send_timeout 300;\n # }\n\n # All other traffic\n location / {\n proxy_pass http://jatos-backend;\n proxy_connect_timeout 300;\n proxy_send_timeout 300;\n proxy_read_timeout 300;\n send_timeout 300;\n }\n }\n}\n")))}d.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/05180b80.046482ec.js b/assets/js/05180b80.046482ec.js new file mode 100644 index 000000000..3703d5638 --- /dev/null +++ b/assets/js/05180b80.046482ec.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[2986],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>m});var r=n(67294);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function i(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var s=r.createContext({}),p=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},c=function(e){var t=p(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,s=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),h=p(n),m=a,d=h["".concat(s,".").concat(m)]||h[m]||u[m]||o;return n?r.createElement(d,i(i({ref:t},c),{},{components:n})):r.createElement(d,i({ref:t},c))}));function m(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=h;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:a,i[1]=l;for(var p=2;p{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>u,frontMatter:()=>o,metadata:()=>l,toc:()=>p});var r=n(83117),a=(n(67294),n(3905));const o={title:"JATOS on AWS",slug:"/JATOS-in-Amazons-Cloud-without-Docker.html",sidebar_position:4},i=void 0,l={unversionedId:"Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker",id:"version-3.7.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker",title:"JATOS on AWS",description:"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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.",source:"@site/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md",sourceDirName:"Serving_the_Internet",slug:"/JATOS-in-Amazons-Cloud-without-Docker.html",permalink:"/3.7.x/JATOS-in-Amazons-Cloud-without-Docker.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:4,frontMatter:{title:"JATOS on AWS",slug:"/JATOS-in-Amazons-Cloud-without-Docker.html",sidebar_position:4},sidebar:"tutorialSidebar",previous:{title:"JATOS on DigitalOcean",permalink:"/3.7.x/JATOS-on-DigitalOcean.html"},next:{title:"Install JATOS on a server",permalink:"/3.7.x/JATOS-on-a-server.html"}},s={},p=[],c={toc:p};function u(e){let{components:t,...n}=e;return(0,a.kt)("wrapper",(0,r.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"On this page is additional information in how to install JATOS on a server on AWS. All general installation advice is in ",(0,a.kt)("a",{parentName:"p",href:"JATOS-on-a-server.html"},"JATOS on a server")," and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for ",(0,a.kt)("a",{parentName:"p",href:"/JATOS-with-Apache.html"},"Apache")," or ",(0,a.kt)("a",{parentName:"p",href:"/JATOS-with-Nginx.html"},"Nginx"),". If you are looking for an easier way to install JATOS in the cloud, the tutorial ",(0,a.kt)("a",{parentName:"p",href:"JATOS-on-DigitalOcean.html"},"JATOS on DigitalOcean")," might be what you are looking for."),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},"First you need to register at ",(0,a.kt)("a",{parentName:"li",href:"https://aws.amazon.com/"},"AWS")," (they'll want your credit card)."),(0,a.kt)("li",{parentName:"ol"},"In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)"),(0,a.kt)("li",{parentName:"ol"},"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."),(0,a.kt)("li",{parentName:"ol"},"Login via SSH: ",(0,a.kt)("inlineCode",{parentName:"li"},"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 ",(0,a.kt)("strong",{parentName:"li"},"public")," one.)"),(0,a.kt)("li",{parentName:"ol"},"Get the latest JATOS: either bundled with Java ",(0,a.kt)("inlineCode",{parentName:"li"},"wget https://github.com/JATOS/JATOS/releases/latest/download/jatos_linux_java.zip")," or without ",(0,a.kt)("inlineCode",{parentName:"li"},"wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip"),". In the latter case you have to install Java yourself."),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("inlineCode",{parentName:"li"},"unzip jatos_linux_java.zip")," (You probably have to install 'unzip' first with ",(0,a.kt)("inlineCode",{parentName:"li"},"sudo apt-get install unzip"),".)"),(0,a.kt)("li",{parentName:"ol"},"If you do ",(0,a.kt)("strong",{parentName:"li"},"not")," use a reverse proxy like ",(0,a.kt)("a",{parentName:"li",href:"/JATOS-with-Nginx.html"},"Nginx")," or ",(0,a.kt)("a",{parentName:"li",href:"/JATOS-with-Apache.html"},"Apache")," you have to configure IP and port in ",(0,a.kt)("inlineCode",{parentName:"li"},"conf/production.conf"),": Use the '",(0,a.kt)("strong",{parentName:"li"},"Private IP"),"' from your instance description (the one that starts with 172.x.x.x) and port 80"),(0,a.kt)("li",{parentName:"ol"},"Allow inbound HTTP/HTTPS traffic: ",(0,a.kt)("a",{parentName:"li",href:"https://aws.amazon.com/premiumsupport/knowledge-center/connect-http-https-ec2/"},"This is done in AWS GUI"),"."),(0,a.kt)("li",{parentName:"ol"},"(Optional) ",(0,a.kt)("a",{parentName:"li",href:"/JATOS-on-a-server.html#9-optional-auto-start-jatos-via-systemd"},"auto-start JATOS")),(0,a.kt)("li",{parentName:"ol"},"Change JATOS' admin password")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/05180b80.c388f3f1.js b/assets/js/05180b80.c388f3f1.js deleted file mode 100644 index e1f9c2720..000000000 --- a/assets/js/05180b80.c388f3f1.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[2986],{3905:(e,t,n)=>{n.d(t,{Zo:()=>c,kt:()=>m});var r=n(67294);function a(e,t,n){return t in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}function o(e,t){var n=Object.keys(e);if(Object.getOwnPropertySymbols){var r=Object.getOwnPropertySymbols(e);t&&(r=r.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),n.push.apply(n,r)}return n}function i(e){for(var t=1;t=0||(a[n]=e[n]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(r=0;r=0||Object.prototype.propertyIsEnumerable.call(e,n)&&(a[n]=e[n])}return a}var s=r.createContext({}),p=function(e){var t=r.useContext(s),n=t;return e&&(n="function"==typeof e?e(t):i(i({},t),e)),n},c=function(e){var t=p(e.components);return r.createElement(s.Provider,{value:t},e.children)},u={inlineCode:"code",wrapper:function(e){var t=e.children;return r.createElement(r.Fragment,{},t)}},h=r.forwardRef((function(e,t){var n=e.components,a=e.mdxType,o=e.originalType,s=e.parentName,c=l(e,["components","mdxType","originalType","parentName"]),h=p(n),m=a,d=h["".concat(s,".").concat(m)]||h[m]||u[m]||o;return n?r.createElement(d,i(i({ref:t},c),{},{components:n})):r.createElement(d,i({ref:t},c))}));function m(e,t){var n=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=n.length,i=new Array(o);i[0]=h;var l={};for(var s in t)hasOwnProperty.call(t,s)&&(l[s]=t[s]);l.originalType=e,l.mdxType="string"==typeof e?e:a,i[1]=l;for(var p=2;p{n.r(t),n.d(t,{assets:()=>s,contentTitle:()=>i,default:()=>u,frontMatter:()=>o,metadata:()=>l,toc:()=>p});var r=n(83117),a=(n(67294),n(3905));const o={title:"JATOS on AWS",slug:"/JATOS-in-Amazons-Cloud-without-Docker.html",sidebar_position:4},i=void 0,l={unversionedId:"Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker",id:"version-3.7.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker",title:"JATOS on AWS",description:"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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.",source:"@site/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md",sourceDirName:"Serving_the_Internet",slug:"/JATOS-in-Amazons-Cloud-without-Docker.html",permalink:"/3.7.x/JATOS-in-Amazons-Cloud-without-Docker.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Serving_the_Internet/JATOS-in-Amazons-Cloud-without-Docker.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:4,frontMatter:{title:"JATOS on AWS",slug:"/JATOS-in-Amazons-Cloud-without-Docker.html",sidebar_position:4},sidebar:"tutorialSidebar",previous:{title:"JATOS on DigitalOcean",permalink:"/3.7.x/JATOS-on-DigitalOcean.html"},next:{title:"Install JATOS on a server",permalink:"/3.7.x/JATOS-on-a-server.html"}},s={},p=[],c={toc:p};function u(e){let{components:t,...n}=e;return(0,a.kt)("wrapper",(0,r.Z)({},c,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"On this page is additional information in how to install JATOS on a server on AWS. All general installation advice is in ",(0,a.kt)("a",{parentName:"p",href:"JATOS-on-a-server.html"},"JATOS on a server")," and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for ",(0,a.kt)("a",{parentName:"p",href:"/JATOS-with-Apache.html"},"Apache")," or ",(0,a.kt)("a",{parentName:"p",href:"/JATOS-with-Nginx.html"},"Nginx"),". If you are looking for an easier way to install JATOS in the cloud, the tutorial ",(0,a.kt)("a",{parentName:"p",href:"JATOS-on-DigitalOcean.html"},"JATOS on DigitalOcean")," might be what you are looking for."),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},"First you need to register at ",(0,a.kt)("a",{parentName:"li",href:"https://aws.amazon.com/"},"AWS")," (they'll want your credit card)."),(0,a.kt)("li",{parentName:"ol"},"In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)"),(0,a.kt)("li",{parentName:"ol"},"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."),(0,a.kt)("li",{parentName:"ol"},"Login via SSH: ",(0,a.kt)("inlineCode",{parentName:"li"},"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 ",(0,a.kt)("strong",{parentName:"li"},"public")," one.)"),(0,a.kt)("li",{parentName:"ol"},"Get the latest JATOS: either bundled with Java ",(0,a.kt)("inlineCode",{parentName:"li"},"wget https://github.com/JATOS/JATOS/releases/latest/download/jatos_linux_java.zip")," or without ",(0,a.kt)("inlineCode",{parentName:"li"},"wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip"),". In the latter case you have to install Java yourself."),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("inlineCode",{parentName:"li"},"unzip jatos_linux_java.zip")," (You probably have to install 'unzip' first with ",(0,a.kt)("inlineCode",{parentName:"li"},"sudo apt-get install unzip"),".)"),(0,a.kt)("li",{parentName:"ol"},"If you do ",(0,a.kt)("strong",{parentName:"li"},"not")," use a reverse proxy like ",(0,a.kt)("a",{parentName:"li",href:"/JATOS-with-Nginx.html"},"Nginx")," or ",(0,a.kt)("a",{parentName:"li",href:"/JATOS-with-Apache.html"},"Apache")," you have to configure IP and port in ",(0,a.kt)("inlineCode",{parentName:"li"},"conf/production.conf"),": Use the '",(0,a.kt)("strong",{parentName:"li"},"Private IP"),"' from your instance description (the one that starts with 172.x.x.x) and port 80"),(0,a.kt)("li",{parentName:"ol"},"Allow inbound HTTP/HTTPS traffic: ",(0,a.kt)("a",{parentName:"li",href:"https://aws.amazon.com/premiumsupport/knowledge-center/connect-http-https-ec2/"},"This is done in AWS GUI"),"."),(0,a.kt)("li",{parentName:"ol"},"(Optional) ",(0,a.kt)("a",{parentName:"li",href:"/JATOS-on-a-server.html#9-optional-auto-start-jatos-via-systemd"},"auto-start JATOS")),(0,a.kt)("li",{parentName:"ol"},"Change JATOS' admin password")))}u.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/06e84cfd.5755e7bb.js b/assets/js/06e84cfd.5755e7bb.js new file mode 100644 index 000000000..085598251 --- /dev/null +++ b/assets/js/06e84cfd.5755e7bb.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[9262],{3905:(e,t,r)=>{r.d(t,{Zo:()=>u,kt:()=>d});var o=r(67294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function n(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,o)}return r}function i(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var p=o.createContext({}),l=function(e){var t=o.useContext(p),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},u=function(e){var t=l(e.components);return o.createElement(p.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},c=o.forwardRef((function(e,t){var r=e.components,a=e.mdxType,n=e.originalType,p=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),c=l(r),d=a,h=c["".concat(p,".").concat(d)]||c[d]||m[d]||n;return r?o.createElement(h,i(i({ref:t},u),{},{components:r})):o.createElement(h,i({ref:t},u))}));function d(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var n=r.length,i=new Array(n);i[0]=c;var s={};for(var p in t)hasOwnProperty.call(t,p)&&(s[p]=t[p]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{r.r(t),r.d(t,{assets:()=>p,contentTitle:()=>i,default:()=>m,frontMatter:()=>n,metadata:()=>s,toc:()=>l});var o=r(83117),a=(r(67294),r(3905));const n={title:"Write Group Studies I - Setup",slug:"/Write-Group-Studies-I-Setup.html",sidebar_position:2},i=void 0,s={unversionedId:"Group_studies/Write-Group-Studies-I-Setup",id:"version-3.7.1/Group_studies/Write-Group-Studies-I-Setup",title:"Write Group Studies I - Setup",description:"Set up group studies",source:"@site/versioned_docs/version-3.7.1/Group_studies/Write-Group-Studies-I-Setup.md",sourceDirName:"Group_studies",slug:"/Write-Group-Studies-I-Setup.html",permalink:"/3.7.x/Write-Group-Studies-I-Setup.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Group_studies/Write-Group-Studies-I-Setup.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:2,frontMatter:{title:"Write Group Studies I - Setup",slug:"/Write-Group-Studies-I-Setup.html",sidebar_position:2},sidebar:"tutorialSidebar",previous:{title:"Example Group Studies",permalink:"/3.7.x/Example-Group-Studies.html"},next:{title:"Write Group Studies II - JavaScript and Messaging",permalink:"/3.7.x/Write-Group-Studies-II-JavaScript-and-Messaging.html"}},p={},l=[{value:"Set up group studies",id:"set-up-group-studies",level:2},{value:"Group settings in each batch's properties",id:"group-settings-in-each-batchs-properties",level:3},{value:"Group assignment",id:"group-assignment",level:2},{value:"Scenario 1: One group, assign workers manually",id:"scenario-1-one-group-assign-workers-manually",level:3},{value:"Scenario 2: Several groups, let JATOS assign workers",id:"scenario-2-several-groups-let-jatos-assign-workers",level:3},{value:"Scenario 3: One open world",id:"scenario-3-one-open-world",level:3},{value:"Scenario 4: Multiple open worlds with limited active members",id:"scenario-4-multiple-open-worlds-with-limited-active-members",level:3}],u={toc:l};function m(e){let{components:t,...n}=e;return(0,a.kt)("wrapper",(0,o.Z)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("h2",{id:"set-up-group-studies"},"Set up group studies"),(0,a.kt)("p",null,"First and common to all group setups is to check the Group study checkbox in the study properties. "),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Group's property",src:r(1701).Z,width:"1902",height:"977"})),(0,a.kt)("p",null,"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."),(0,a.kt)("h3",{id:"group-settings-in-each-batchs-properties"},"Group settings in each batch's properties"),(0,a.kt)("p",null,"You can have multiple batches in JATOS, each one with different group settings. There are three important bits of information for a group study:"),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Study Links screenshot",src:r(14571).Z,width:"1919",height:"945"})),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("strong",{parentName:"li"},"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."),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("strong",{parentName:"li"},"Max total members"),": This limits the number of members a single group can have. While there can be multiple groups in a batch, the ",(0,a.kt)("em",{parentName:"li"},"Max total members")," field applies to each separate group. "),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("strong",{parentName:"li"},"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.")),(0,a.kt)("p",null,"By default, all properties have no upper limit."),(0,a.kt)("h2",{id:"group-assignment"},"Group assignment"),(0,a.kt)("p",null,"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."),(0,a.kt)("h3",{id:"scenario-1-one-group-assign-workers-manually"},"Scenario 1: One group, assign workers manually"),(0,a.kt)("p",null,"If in a batch you set the ",(0,a.kt)("em",{parentName:"p"},"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 ",(0,a.kt)("a",{parentName:"p",href:"Run-your-Study-with-Study-Links.html"},"create two Personal Single study links")," (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."),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Prisoners example",src:r(4077).Z,width:"490",height:"353"})),(0,a.kt)("p",null,"The first two scenarios may apply to the ",(0,a.kt)("a",{parentName:"p",href:"/Example-Studies"},"Prisoner's Dilemma Example Study"),"."),(0,a.kt)("h3",{id:"scenario-2-several-groups-let-jatos-assign-workers"},"Scenario 2: Several groups, let JATOS assign workers"),(0,a.kt)("p",null,"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 ",(0,a.kt)("em",{parentName:"p"},"Max total workers")," to 6 and both ",(0,a.kt)("em",{parentName:"p"},"Max active members")," and ",(0,a.kt)("em",{parentName:"p"},"Max total members")," to 2 (remember that these numbers apply to each group separately). Then ",(0,a.kt)("a",{parentName:"p",href:"Run-your-Study-with-Study-Links.html"},"create 6 Personal Single study links")," (but other study link types are fine too) and send them to your 6 participants."),(0,a.kt)("h3",{id:"scenario-3-one-open-world"},"Scenario 3: One open world"),(0,a.kt)("p",null,"This scenario is basically the opposite of the first one. By limiting neither the ",(0,a.kt)("em",{parentName:"p"},"Max total worker")," nor the ",(0,a.kt)("em",{parentName:"p"},"Max total members"),", nor the ",(0,a.kt)("em",{parentName:"p"},"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 ",(0,a.kt)("a",{parentName:"p",href:"Run-your-Study-with-Study-Links.html"},"create one study link type General Single")," (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website)."),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Snake example",src:r(50849).Z,width:"534",height:"353"})),(0,a.kt)("p",null,"The third and fourth scenario may apply to the ",(0,a.kt)("a",{parentName:"p",href:"/Example-Studies"},"Snake Example Study"),"."),(0,a.kt)("h3",{id:"scenario-4-multiple-open-worlds-with-limited-active-members"},"Scenario 4: Multiple open worlds with limited active members"),(0,a.kt)("p",null,"Say you want to have groups with up to 3 members, interacting ",(0,a.kt)("em",{parentName:"p"},"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 ",(0,a.kt)("em",{parentName:"p"},"Max active members")," to 3, and leave ",(0,a.kt)("em",{parentName:"p"},"Max total worker")," and ",(0,a.kt)("em",{parentName:"p"},"Max total members")," unlimited."))}m.isMDXComponent=!0},14571:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/batch_properties_groups-0c2cce8e3339ba04a59eab7d722a4244.png"},4077:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/prisoners_example-5d648405095710de61794774e16431cf.png"},50849:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/snake_example-4f9f11717583cc9b10ecf83adcdaf3e6.png"},1701:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/study-properties-group-study-00985d0ba1c509a8a47ccf569d481a65.png"}}]); \ No newline at end of file diff --git a/assets/js/06e84cfd.c2c5dc5c.js b/assets/js/06e84cfd.c2c5dc5c.js deleted file mode 100644 index 533566876..000000000 --- a/assets/js/06e84cfd.c2c5dc5c.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[9262],{3905:(e,t,r)=>{r.d(t,{Zo:()=>u,kt:()=>d});var o=r(67294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function n(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);t&&(o=o.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,o)}return r}function i(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(o=0;o=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var p=o.createContext({}),l=function(e){var t=o.useContext(p),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},u=function(e){var t=l(e.components);return o.createElement(p.Provider,{value:t},e.children)},m={inlineCode:"code",wrapper:function(e){var t=e.children;return o.createElement(o.Fragment,{},t)}},c=o.forwardRef((function(e,t){var r=e.components,a=e.mdxType,n=e.originalType,p=e.parentName,u=s(e,["components","mdxType","originalType","parentName"]),c=l(r),d=a,h=c["".concat(p,".").concat(d)]||c[d]||m[d]||n;return r?o.createElement(h,i(i({ref:t},u),{},{components:r})):o.createElement(h,i({ref:t},u))}));function d(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var n=r.length,i=new Array(n);i[0]=c;var s={};for(var p in t)hasOwnProperty.call(t,p)&&(s[p]=t[p]);s.originalType=e,s.mdxType="string"==typeof e?e:a,i[1]=s;for(var l=2;l{r.r(t),r.d(t,{assets:()=>p,contentTitle:()=>i,default:()=>m,frontMatter:()=>n,metadata:()=>s,toc:()=>l});var o=r(83117),a=(r(67294),r(3905));const n={title:"Write Group Studies I - Setup",slug:"/Write-Group-Studies-I-Setup.html",sidebar_position:2},i=void 0,s={unversionedId:"Group_studies/Write-Group-Studies-I-Setup",id:"version-3.7.1/Group_studies/Write-Group-Studies-I-Setup",title:"Write Group Studies I - Setup",description:"Set up group studies",source:"@site/versioned_docs/version-3.7.1/Group_studies/Write-Group-Studies-I-Setup.md",sourceDirName:"Group_studies",slug:"/Write-Group-Studies-I-Setup.html",permalink:"/3.7.x/Write-Group-Studies-I-Setup.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Group_studies/Write-Group-Studies-I-Setup.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:2,frontMatter:{title:"Write Group Studies I - Setup",slug:"/Write-Group-Studies-I-Setup.html",sidebar_position:2},sidebar:"tutorialSidebar",previous:{title:"Example Group Studies",permalink:"/3.7.x/Example-Group-Studies.html"},next:{title:"Write Group Studies II - JavaScript and Messaging",permalink:"/3.7.x/Write-Group-Studies-II-JavaScript-and-Messaging.html"}},p={},l=[{value:"Set up group studies",id:"set-up-group-studies",level:2},{value:"Group settings in each batch's properties",id:"group-settings-in-each-batchs-properties",level:3},{value:"Group assignment",id:"group-assignment",level:2},{value:"Scenario 1: One group, assign workers manually",id:"scenario-1-one-group-assign-workers-manually",level:3},{value:"Scenario 2: Several groups, let JATOS assign workers",id:"scenario-2-several-groups-let-jatos-assign-workers",level:3},{value:"Scenario 3: One open world",id:"scenario-3-one-open-world",level:3},{value:"Scenario 4: Multiple open worlds with limited active members",id:"scenario-4-multiple-open-worlds-with-limited-active-members",level:3}],u={toc:l};function m(e){let{components:t,...n}=e;return(0,a.kt)("wrapper",(0,o.Z)({},u,n,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("h2",{id:"set-up-group-studies"},"Set up group studies"),(0,a.kt)("p",null,"First and common to all group setups is to check the Group study checkbox in the study properties. "),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Group's property",src:r(1701).Z,width:"1902",height:"977"})),(0,a.kt)("p",null,"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."),(0,a.kt)("h3",{id:"group-settings-in-each-batchs-properties"},"Group settings in each batch's properties"),(0,a.kt)("p",null,"You can have multiple batches in JATOS, each one with different group settings. There are three important bits of information for a group study:"),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Study Links screenshot",src:r(14571).Z,width:"1919",height:"945"})),(0,a.kt)("ol",null,(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("strong",{parentName:"li"},"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."),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("strong",{parentName:"li"},"Max total members"),": This limits the number of members a single group can have. While there can be multiple groups in a batch, the ",(0,a.kt)("em",{parentName:"li"},"Max total members")," field applies to each separate group. "),(0,a.kt)("li",{parentName:"ol"},(0,a.kt)("strong",{parentName:"li"},"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.")),(0,a.kt)("p",null,"By default, all properties have no upper limit."),(0,a.kt)("h2",{id:"group-assignment"},"Group assignment"),(0,a.kt)("p",null,"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."),(0,a.kt)("h3",{id:"scenario-1-one-group-assign-workers-manually"},"Scenario 1: One group, assign workers manually"),(0,a.kt)("p",null,"If in a batch you set the ",(0,a.kt)("em",{parentName:"p"},"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 ",(0,a.kt)("a",{parentName:"p",href:"Run-your-Study-with-Study-Links.html"},"create two Personal Single study links")," (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."),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Prisoners example",src:r(4077).Z,width:"490",height:"353"})),(0,a.kt)("p",null,"The first two scenarios may apply to the ",(0,a.kt)("a",{parentName:"p",href:"/Example-Studies"},"Prisoner's Dilemma Example Study"),"."),(0,a.kt)("h3",{id:"scenario-2-several-groups-let-jatos-assign-workers"},"Scenario 2: Several groups, let JATOS assign workers"),(0,a.kt)("p",null,"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 ",(0,a.kt)("em",{parentName:"p"},"Max total workers")," to 6 and both ",(0,a.kt)("em",{parentName:"p"},"Max active members")," and ",(0,a.kt)("em",{parentName:"p"},"Max total members")," to 2 (remember that these numbers apply to each group separately). Then ",(0,a.kt)("a",{parentName:"p",href:"Run-your-Study-with-Study-Links.html"},"create 6 Personal Single study links")," (but other study link types are fine too) and send them to your 6 participants."),(0,a.kt)("h3",{id:"scenario-3-one-open-world"},"Scenario 3: One open world"),(0,a.kt)("p",null,"This scenario is basically the opposite of the first one. By limiting neither the ",(0,a.kt)("em",{parentName:"p"},"Max total worker")," nor the ",(0,a.kt)("em",{parentName:"p"},"Max total members"),", nor the ",(0,a.kt)("em",{parentName:"p"},"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 ",(0,a.kt)("a",{parentName:"p",href:"Run-your-Study-with-Study-Links.html"},"create one study link type General Single")," (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website)."),(0,a.kt)("p",null,(0,a.kt)("img",{alt:"Snake example",src:r(50849).Z,width:"534",height:"353"})),(0,a.kt)("p",null,"The third and fourth scenario may apply to the ",(0,a.kt)("a",{parentName:"p",href:"/Example-Studies"},"Snake Example Study"),"."),(0,a.kt)("h3",{id:"scenario-4-multiple-open-worlds-with-limited-active-members"},"Scenario 4: Multiple open worlds with limited active members"),(0,a.kt)("p",null,"Say you want to have groups with up to 3 members, interacting ",(0,a.kt)("em",{parentName:"p"},"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 ",(0,a.kt)("em",{parentName:"p"},"Max active members")," to 3, and leave ",(0,a.kt)("em",{parentName:"p"},"Max total worker")," and ",(0,a.kt)("em",{parentName:"p"},"Max total members")," unlimited."))}m.isMDXComponent=!0},14571:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/batch_properties_groups-0c2cce8e3339ba04a59eab7d722a4244.png"},4077:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/prisoners_example-5d648405095710de61794774e16431cf.png"},50849:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/snake_example-4f9f11717583cc9b10ecf83adcdaf3e6.png"},1701:(e,t,r)=>{r.d(t,{Z:()=>o});const o=r.p+"assets/images/study-properties-group-study-00985d0ba1c509a8a47ccf569d481a65.png"}}]); \ No newline at end of file diff --git a/assets/js/0827edb3.5b6e3cf3.js b/assets/js/0827edb3.5b6e3cf3.js new file mode 100644 index 000000000..016fd27ac --- /dev/null +++ b/assets/js/0827edb3.5b6e3cf3.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[7112],{3905:(e,t,r)=>{r.d(t,{Zo:()=>c,kt:()=>m});var a=r(67294);function n(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,a)}return r}function o(e){for(var t=1;t=0||(n[r]=e[r]);return n}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(n[r]=e[r])}return n}var l=a.createContext({}),p=function(e){var t=a.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):o(o({},t),e)),r},c=function(e){var t=p(e.components);return a.createElement(l.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var r=e.components,n=e.mdxType,i=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),u=p(r),m=n,f=u["".concat(l,".").concat(m)]||u[m]||d[m]||i;return r?a.createElement(f,o(o({ref:t},c),{},{components:r})):a.createElement(f,o({ref:t},c))}));function m(e,t){var r=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var i=r.length,o=new Array(i);o[0]=u;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:n,o[1]=s;for(var p=2;p{r.r(t),r.d(t,{assets:()=>l,contentTitle:()=>o,default:()=>d,frontMatter:()=>i,metadata:()=>s,toc:()=>p});var a=r(83117),n=(r(67294),r(3905));const i={title:"Use Prolific",slug:"/Use-Prolific.html",sidebar_position:7},o=void 0,s={unversionedId:"Run_your_study/Use-Prolific",id:"version-3.6.1/Run_your_study/Use-Prolific",title:"Use Prolific",description:"It is very easy to use JATOS together with Prolific to recruit participants.",source:"@site/versioned_docs/version-3.6.1/Run_your_study/Use-Prolific.md",sourceDirName:"Run_your_study",slug:"/Use-Prolific.html",permalink:"/3.6.x/Use-Prolific.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.6.1/Run_your_study/Use-Prolific.md",tags:[],version:"3.6.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:7,frontMatter:{title:"Use Prolific",slug:"/Use-Prolific.html",sidebar_position:7},sidebar:"version-3.6.1/tutorialSidebar",previous:{title:"Use MTurk",permalink:"/3.6.x/Connect-to-Mechanical-Turk.html"},next:{title:"Write cross-sectional and longitudinal studies",permalink:"/3.6.x/Cross-sectional-and-longitudinal-studies.html"}},l={},p=[{value:"1. Enter your JATOS study link",id:"1-enter-your-jatos-study-link",level:2},{value:"2. (Optional) Consider passing Prolific URL parameters to your study",id:"2-optional-consider-passing-prolific-url-parameters-to-your-study",level:2},{value:"3. Redirect to Prolific's end page after the study is done",id:"3-redirect-to-prolifics-end-page-after-the-study-is-done",level:2}],c={toc:p};function d(e){let{components:t,...i}=e;return(0,n.kt)("wrapper",(0,a.Z)({},c,i,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,"It is very easy to use JATOS together with ",(0,n.kt)("a",{parentName:"p",href:"https://www.prolific.co/"},"Prolific")," to recruit participants. "),(0,n.kt)("p",null,"This is what the ",(0,n.kt)("em",{parentName:"p"},"New Study")," page in Prolific looks like:"),(0,n.kt)("p",null,(0,n.kt)("img",{alt:"Prolific screenshot",src:r(33478).Z,width:"1366",height:"751"})),(0,n.kt)("h2",{id:"1-enter-your-jatos-study-link"},"1. Enter your JATOS study link"),(0,n.kt)("p",null,"In the field under ",(0,n.kt)("em",{parentName:"p"},"What is the URL of your study?")," (first red box in the screenshot), enter a link to your JATOS study.You probably want a link to either a ",(0,n.kt)("em",{parentName:"p"},"General Single")," or a ",(0,n.kt)("em",{parentName:"p"},"General Multiple")," worker type (see ",(0,n.kt)("a",{parentName:"p",href:"Worker-Types.html"},"JATOS' worker types")," and ",(0,n.kt)("a",{parentName:"p",href:"Run-your-Study-with-Worker-and-Batch-Manager.html"},"Run your Study with Worker & Batch Manager"),")."),(0,n.kt)("h2",{id:"2-optional-consider-passing-prolific-url-parameters-to-your-study"},"2. (Optional) Consider passing Prolific URL parameters to your study"),(0,n.kt)("p",null,"Prolific allows you to pass the parameters PROLIFIC PID, STUDY ID, and SESSION ID as URL parameters. Click on 'Show advanced' and then 'Add parameters' like in the screenshot."),(0,n.kt)("p",null,(0,n.kt)("img",{alt:"Prolific screenshot",src:r(28095).Z,width:"3774",height:"2526"})),(0,n.kt)("p",null,"Then you can access those URL parameters in your study's JavaScript via ",(0,n.kt)("a",{parentName:"p",href:"jatos.js-Reference.html#original-url-query-parameters"},"jatos.urlQueryParameters"),"."),(0,n.kt)("h2",{id:"3-redirect-to-prolifics-end-page-after-the-study-is-done"},"3. Redirect to Prolific's end page after the study is done"),(0,n.kt)("p",null,"The second red box contains a link that will (re)direct the participant to a Prolific page, with information on how to claim their payment."),(0,n.kt)("p",null,(0,n.kt)("strong",{parentName:"p"},"Choose one of the three ways")," (differ in JATOS version and your preferences)"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Include ",(0,n.kt)("a",{parentName:"p",href:"jatos.js-Reference.html#jatosendstudyajax"},(0,n.kt)("inlineCode",{parentName:"a"},"jatos.endStudyAjax"))," in the JavaScript of your ",(0,n.kt)("strong",{parentName:"p"},"last")," component (works with ",(0,n.kt)("strong",{parentName:"p"},"all JATOS versions"),")"),(0,n.kt)("p",{parentName:"li"},"All you need to do is call ",(0,n.kt)("inlineCode",{parentName:"p"},"jatos.endStudyAjax"),", and add a callback that will replace ",(0,n.kt)("inlineCode",{parentName:"p"},"window.location.href")," with the Prolific end page once the ajax call is ",(0,n.kt)("inlineCode",{parentName:"p"},"done"),":"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-JavaScript"},"jatos.endStudyAjax().then(() => {\n // Change this URL to the one you see in Prolific\n window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'\n});\n")),(0,n.kt)("p",{parentName:"li"},"Of course, this can also be done together with ",(0,n.kt)("inlineCode",{parentName:"p"},"jatos.submitResultData")," if you want to store result data in JATOS:"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-JavaScript"},"var result = { test: \"some results\" };\njatos.submitResultData(result)\n .then(jatos.endStudyAjax)\n .then(() => {\n window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'\n});\n")),(0,n.kt)("p",{parentName:"li"},"We provide a ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/JATOS/JATOS_examples/raw/main/examples/prolific_example.zip"},"Prolific example study")," that you can use as a template.")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Setup ",(0,n.kt)("strong",{parentName:"p"},"End Redirect URL")," in the Study Properties (easiest - but only ",(0,n.kt)("strong",{parentName:"p"},"since JATOS v3.5.1"),")"),(0,n.kt)("p",{parentName:"li"},"In JATOS GUI you can put the in Prolific link in the ",(0,n.kt)("strong",{parentName:"p"},"End Redirect URL")," field of your Study Properties"),(0,n.kt)("p",{parentName:"li"},(0,n.kt)("img",{alt:"screenshot",src:r(87043).Z,width:"1906",height:"879"}))),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Include ",(0,n.kt)("a",{parentName:"p",href:"jatos.js-Reference.html#jatosendstudyandredirect"},(0,n.kt)("inlineCode",{parentName:"a"},"jatos.endStudyAndRedirect"))," in the JavaScript of your ",(0,n.kt)("strong",{parentName:"p"},"last")," component (",(0,n.kt)("strong",{parentName:"p"},"since JATOS v3.5.1"),")"),(0,n.kt)("p",{parentName:"li"},"E.g. but change this URL to the one you see in Prolific"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-javascript"},'// Change this URL the one you see in Prolific\njatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");\n')),(0,n.kt)("p",{parentName:"li"},"You can even combine it with sending result data"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-javascript"},'var resultData = {id: 123, data: "my important result data"};\njatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);\n')))))}d.isMDXComponent=!0},33478:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/Screenshot_Prolific_create_study-97d069e806f37550f7c0c771a958fa22.png"},28095:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/Screenshot_Prolific_query_parameter-3d35afd80565777bb63f2df155cdef8e.png"},87043:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/Screenshot_end-redirect-url-c3520fefdf5d82a83a5a68b0138c8ad9.png"}}]); \ No newline at end of file diff --git a/assets/js/0827edb3.d83bff09.js b/assets/js/0827edb3.d83bff09.js deleted file mode 100644 index ee43fdd37..000000000 --- a/assets/js/0827edb3.d83bff09.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[7112],{3905:(e,t,r)=>{r.d(t,{Zo:()=>c,kt:()=>m});var a=r(67294);function n(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function i(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,a)}return r}function o(e){for(var t=1;t=0||(n[r]=e[r]);return n}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(n[r]=e[r])}return n}var l=a.createContext({}),p=function(e){var t=a.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):o(o({},t),e)),r},c=function(e){var t=p(e.components);return a.createElement(l.Provider,{value:t},e.children)},d={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},u=a.forwardRef((function(e,t){var r=e.components,n=e.mdxType,i=e.originalType,l=e.parentName,c=s(e,["components","mdxType","originalType","parentName"]),u=p(r),m=n,f=u["".concat(l,".").concat(m)]||u[m]||d[m]||i;return r?a.createElement(f,o(o({ref:t},c),{},{components:r})):a.createElement(f,o({ref:t},c))}));function m(e,t){var r=arguments,n=t&&t.mdxType;if("string"==typeof e||n){var i=r.length,o=new Array(i);o[0]=u;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:n,o[1]=s;for(var p=2;p{r.r(t),r.d(t,{assets:()=>l,contentTitle:()=>o,default:()=>d,frontMatter:()=>i,metadata:()=>s,toc:()=>p});var a=r(83117),n=(r(67294),r(3905));const i={title:"Use Prolific",slug:"/Use-Prolific.html",sidebar_position:7},o=void 0,s={unversionedId:"Run_your_study/Use-Prolific",id:"version-3.6.1/Run_your_study/Use-Prolific",title:"Use Prolific",description:"It is very easy to use JATOS together with Prolific to recruit participants.",source:"@site/versioned_docs/version-3.6.1/Run_your_study/Use-Prolific.md",sourceDirName:"Run_your_study",slug:"/Use-Prolific.html",permalink:"/3.6.x/Use-Prolific.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.6.1/Run_your_study/Use-Prolific.md",tags:[],version:"3.6.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:7,frontMatter:{title:"Use Prolific",slug:"/Use-Prolific.html",sidebar_position:7},sidebar:"version-3.6.1/tutorialSidebar",previous:{title:"Use MTurk",permalink:"/3.6.x/Connect-to-Mechanical-Turk.html"},next:{title:"Write cross-sectional and longitudinal studies",permalink:"/3.6.x/Cross-sectional-and-longitudinal-studies.html"}},l={},p=[{value:"1. Enter your JATOS study link",id:"1-enter-your-jatos-study-link",level:2},{value:"2. (Optional) Consider passing Prolific URL parameters to your study",id:"2-optional-consider-passing-prolific-url-parameters-to-your-study",level:2},{value:"3. Redirect to Prolific's end page after the study is done",id:"3-redirect-to-prolifics-end-page-after-the-study-is-done",level:2}],c={toc:p};function d(e){let{components:t,...i}=e;return(0,n.kt)("wrapper",(0,a.Z)({},c,i,{components:t,mdxType:"MDXLayout"}),(0,n.kt)("p",null,"It is very easy to use JATOS together with ",(0,n.kt)("a",{parentName:"p",href:"https://www.prolific.co/"},"Prolific")," to recruit participants. "),(0,n.kt)("p",null,"This is what the ",(0,n.kt)("em",{parentName:"p"},"New Study")," page in Prolific looks like:"),(0,n.kt)("p",null,(0,n.kt)("img",{alt:"Prolific screenshot",src:r(33478).Z,width:"1366",height:"751"})),(0,n.kt)("h2",{id:"1-enter-your-jatos-study-link"},"1. Enter your JATOS study link"),(0,n.kt)("p",null,"In the field under ",(0,n.kt)("em",{parentName:"p"},"What is the URL of your study?")," (first red box in the screenshot), enter a link to your JATOS study.You probably want a link to either a ",(0,n.kt)("em",{parentName:"p"},"General Single")," or a ",(0,n.kt)("em",{parentName:"p"},"General Multiple")," worker type (see ",(0,n.kt)("a",{parentName:"p",href:"Worker-Types.html"},"JATOS' worker types")," and ",(0,n.kt)("a",{parentName:"p",href:"Run-your-Study-with-Worker-and-Batch-Manager.html"},"Run your Study with Worker & Batch Manager"),")."),(0,n.kt)("h2",{id:"2-optional-consider-passing-prolific-url-parameters-to-your-study"},"2. (Optional) Consider passing Prolific URL parameters to your study"),(0,n.kt)("p",null,"Prolific allows you to pass the parameters PROLIFIC PID, STUDY ID, and SESSION ID as URL parameters. Click on 'Show advanced' and then 'Add parameters' like in the screenshot."),(0,n.kt)("p",null,(0,n.kt)("img",{alt:"Prolific screenshot",src:r(28095).Z,width:"3774",height:"2526"})),(0,n.kt)("p",null,"Then you can access those URL parameters in your study's JavaScript via ",(0,n.kt)("a",{parentName:"p",href:"jatos.js-Reference.html#original-url-query-parameters"},"jatos.urlQueryParameters"),"."),(0,n.kt)("h2",{id:"3-redirect-to-prolifics-end-page-after-the-study-is-done"},"3. Redirect to Prolific's end page after the study is done"),(0,n.kt)("p",null,"The second red box contains a link that will (re)direct the participant to a Prolific page, with information on how to claim their payment."),(0,n.kt)("p",null,(0,n.kt)("strong",{parentName:"p"},"Choose one of the three ways")," (differ in JATOS version and your preferences)"),(0,n.kt)("ol",null,(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Include ",(0,n.kt)("a",{parentName:"p",href:"jatos.js-Reference.html#jatosendstudyajax"},(0,n.kt)("inlineCode",{parentName:"a"},"jatos.endStudyAjax"))," in the JavaScript of your ",(0,n.kt)("strong",{parentName:"p"},"last")," component (works with ",(0,n.kt)("strong",{parentName:"p"},"all JATOS versions"),")"),(0,n.kt)("p",{parentName:"li"},"All you need to do is call ",(0,n.kt)("inlineCode",{parentName:"p"},"jatos.endStudyAjax"),", and add a callback that will replace ",(0,n.kt)("inlineCode",{parentName:"p"},"window.location.href")," with the Prolific end page once the ajax call is ",(0,n.kt)("inlineCode",{parentName:"p"},"done"),":"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-JavaScript"},"jatos.endStudyAjax().then(() => {\n // Change this URL to the one you see in Prolific\n window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'\n});\n")),(0,n.kt)("p",{parentName:"li"},"Of course, this can also be done together with ",(0,n.kt)("inlineCode",{parentName:"p"},"jatos.submitResultData")," if you want to store result data in JATOS:"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-JavaScript"},"var result = { test: \"some results\" };\njatos.submitResultData(result)\n .then(jatos.endStudyAjax)\n .then(() => {\n window.location.href = 'https://app.prolific.co/submissions/complete?cc=1234ABCD'\n});\n")),(0,n.kt)("p",{parentName:"li"},"We provide a ",(0,n.kt)("a",{parentName:"p",href:"https://github.com/JATOS/JATOS_examples/raw/main/examples/prolific_example.zip"},"Prolific example study")," that you can use as a template.")),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Setup ",(0,n.kt)("strong",{parentName:"p"},"End Redirect URL")," in the Study Properties (easiest - but only ",(0,n.kt)("strong",{parentName:"p"},"since JATOS v3.5.1"),")"),(0,n.kt)("p",{parentName:"li"},"In JATOS GUI you can put the in Prolific link in the ",(0,n.kt)("strong",{parentName:"p"},"End Redirect URL")," field of your Study Properties"),(0,n.kt)("p",{parentName:"li"},(0,n.kt)("img",{alt:"screenshot",src:r(87043).Z,width:"1906",height:"879"}))),(0,n.kt)("li",{parentName:"ol"},(0,n.kt)("p",{parentName:"li"},"Include ",(0,n.kt)("a",{parentName:"p",href:"jatos.js-Reference.html#jatosendstudyandredirect"},(0,n.kt)("inlineCode",{parentName:"a"},"jatos.endStudyAndRedirect"))," in the JavaScript of your ",(0,n.kt)("strong",{parentName:"p"},"last")," component (",(0,n.kt)("strong",{parentName:"p"},"since JATOS v3.5.1"),")"),(0,n.kt)("p",{parentName:"li"},"E.g. but change this URL to the one you see in Prolific"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-javascript"},'// Change this URL the one you see in Prolific\njatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");\n')),(0,n.kt)("p",{parentName:"li"},"You can even combine it with sending result data"),(0,n.kt)("pre",{parentName:"li"},(0,n.kt)("code",{parentName:"pre",className:"language-javascript"},'var resultData = {id: 123, data: "my important result data"};\njatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);\n')))))}d.isMDXComponent=!0},33478:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/Screenshot_Prolific_create_study-97d069e806f37550f7c0c771a958fa22.png"},28095:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/Screenshot_Prolific_query_parameter-3d35afd80565777bb63f2df155cdef8e.png"},87043:(e,t,r)=>{r.d(t,{Z:()=>a});const a=r.p+"assets/images/Screenshot_end-redirect-url-c3520fefdf5d82a83a5a68b0138c8ad9.png"}}]); \ No newline at end of file diff --git a/assets/js/0994c97b.499830fd.js b/assets/js/0994c97b.499830fd.js deleted file mode 100644 index c829d05b7..000000000 --- a/assets/js/0994c97b.499830fd.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[5145],{3905:(e,t,r)=>{r.d(t,{Zo:()=>l,kt:()=>c});var n=r(67294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function s(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var u=n.createContext({}),d=function(e){var t=n.useContext(u),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},l=function(e){var t=d(e.components);return n.createElement(u.Provider,{value:t},e.children)},y={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},p=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,o=e.originalType,u=e.parentName,l=i(e,["components","mdxType","originalType","parentName"]),p=d(r),c=a,m=p["".concat(u,".").concat(c)]||p[c]||y[c]||o;return r?n.createElement(m,s(s({ref:t},l),{},{components:r})):n.createElement(m,s({ref:t},l))}));function c(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=r.length,s=new Array(o);s[0]=p;var i={};for(var u in t)hasOwnProperty.call(t,u)&&(i[u]=t[u]);i.originalType=e,i.mdxType="string"==typeof e?e:a,s[1]=i;for(var d=2;d{r.r(t),r.d(t,{assets:()=>u,contentTitle:()=>s,default:()=>y,frontMatter:()=>o,metadata:()=>i,toc:()=>d});var n=r(83117),a=(r(67294),r(3905));const o={title:"Create a new study",slug:"/Create-a-new-study.html",sidebar_position:1},s=void 0,i={unversionedId:"Write_your_study/Create-a-new-study",id:"Write_your_study/Create-a-new-study",title:"Create a new study",description:"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 or Adapt Pre written Code to run it in JATOS.",source:"@site/docs/Write_your_study/Create-a-new-study.md",sourceDirName:"Write_your_study",slug:"/Create-a-new-study.html",permalink:"/next/Create-a-new-study.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/docs/Write_your_study/Create-a-new-study.md",tags:[],version:"current",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:1,frontMatter:{title:"Create a new study",slug:"/Create-a-new-study.html",sidebar_position:1},sidebar:"tutorialSidebar",previous:{title:"JATOS Tryout Server",permalink:"/next/JATOS-Tryout-Server.html"},next:{title:"Write your own Study - Basics and Beyond",permalink:"/next/Write-your-own-Study-Basics-and-Beyond.html"}},u={},d=[{value:"Use a builder - OpenSesame/OSWeb and lab.js",id:"use-a-builder---opensesameosweb-and-labjs",level:3},{value:"Use jsPsych",id:"use-jspsych",level:3},{value:"Write your own study from scratch",id:"write-your-own-study-from-scratch",level:3},{value:"Modify an existing study",id:"modify-an-existing-study",level:3}],l={toc:d};function y(e){let{components:t,...r}=e;return(0,a.kt)("wrapper",(0,n.Z)({},l,r,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"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 ",(0,a.kt)("a",{parentName:"p",href:"Write-your-own-Study-Basics-and-Beyond.html"},"Write your own Study - Basics and Beyond")," or ",(0,a.kt)("a",{parentName:"p",href:"Adapt-pre-written-code-to-run-it-in-JATOS.html"},"Adapt Pre written Code to run it in JATOS"),"."),(0,a.kt)("p",null,(0,a.kt)("strong",{parentName:"p"},"Developement of a JATOS study usually happens on your local JATOS: ",(0,a.kt)("a",{parentName:"strong",href:"Run-an-experiment-with-JATOS-Workflow.html"},"Run an experiment with JATOS - Workflow"))),(0,a.kt)("h3",{id:"use-a-builder---opensesameosweb-and-labjs"},"Use a builder - OpenSesame/OSWeb and lab.js"),(0,a.kt)("p",null,"Experiment builders like ",(0,a.kt)("a",{parentName:"p",href:"OSWeb-and-JATOS.html"},"OpenSesame/OSWeb")," and ",(0,a.kt)("a",{parentName:"p",href:"labjs-and-JATOS.html"},"lab.js")," 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."),(0,a.kt)("h3",{id:"use-jspsych"},"Use jsPsych"),(0,a.kt)("p",null,(0,a.kt)("a",{parentName:"p",href:"http://www.jspsych.org/"},"jsPsych")," is a popular library for running behavioral experiments in a web browser. We have an own web page describing using ",(0,a.kt)("a",{parentName:"p",href:"jsPsych-and-JATOS.html"},"jsPsych with JATOS"),"."),(0,a.kt)("h3",{id:"write-your-own-study-from-scratch"},"Write your own study from scratch"),(0,a.kt)("p",null,"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."),(0,a.kt)("p",null,"Go to the study sidebar by clicking on ",(0,a.kt)("strong",{parentName:"p"},"Studies"),' in the header, top-left, then click on "',(0,a.kt)("strong",{parentName:"p"},"+"),'" and select ',(0,a.kt)("strong",{parentName:"p"},"New Study"),". Now an dialog opens where you can enter a title for the study and finally ",(0,a.kt)("strong",{parentName:"p"},"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 ",(0,a.kt)("strong",{parentName:"p"},"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."),(0,a.kt)("h3",{id:"modify-an-existing-study"},"Modify an existing study"),(0,a.kt)("p",null,"Take an existing study (e.g. from ",(0,a.kt)("a",{parentName:"p",href:"/Example-Studies"},"Example Studies"),") as a prototype and modify it bit by bit. Go to the study sidebar by clicking on ",(0,a.kt)("strong",{parentName:"p"},"Studies"),' in the header, top-left, then click on "',(0,a.kt)("strong",{parentName:"p"},"+"),'" and select ',(0,a.kt)("strong",{parentName:"p"},"Import Study"),". Then modify the source code in your ",(0,a.kt)("strong",{parentName:"p"},"study assets")," folder, which is usually in your JATOS installation folder."))}y.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/1740d8df.fe8372f4.js b/assets/js/0994c97b.5852e311.js similarity index 58% rename from assets/js/1740d8df.fe8372f4.js rename to assets/js/0994c97b.5852e311.js index e86502541..38bbb0375 100644 --- a/assets/js/1740d8df.fe8372f4.js +++ b/assets/js/0994c97b.5852e311.js @@ -1 +1 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[3194],{3905:(e,t,r)=>{r.d(t,{Zo:()=>l,kt:()=>c});var n=r(67294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function s(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var u=n.createContext({}),d=function(e){var t=n.useContext(u),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},l=function(e){var t=d(e.components);return n.createElement(u.Provider,{value:t},e.children)},y={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},p=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,o=e.originalType,u=e.parentName,l=i(e,["components","mdxType","originalType","parentName"]),p=d(r),c=a,h=p["".concat(u,".").concat(c)]||p[c]||y[c]||o;return r?n.createElement(h,s(s({ref:t},l),{},{components:r})):n.createElement(h,s({ref:t},l))}));function c(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=r.length,s=new Array(o);s[0]=p;var i={};for(var u in t)hasOwnProperty.call(t,u)&&(i[u]=t[u]);i.originalType=e,i.mdxType="string"==typeof e?e:a,s[1]=i;for(var d=2;d{r.r(t),r.d(t,{assets:()=>u,contentTitle:()=>s,default:()=>y,frontMatter:()=>o,metadata:()=>i,toc:()=>d});var n=r(83117),a=(r(67294),r(3905));const o={title:"Create a new study",slug:"/Create-a-new-study.html",sidebar_position:1},s=void 0,i={unversionedId:"Write_your_study/Create-a-new-study",id:"version-3.7.1/Write_your_study/Create-a-new-study",title:"Create a new study",description:"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 or Adapt Pre written Code to run it in JATOS.",source:"@site/versioned_docs/version-3.7.1/Write_your_study/Create-a-new-study.md",sourceDirName:"Write_your_study",slug:"/Create-a-new-study.html",permalink:"/3.7.x/Create-a-new-study.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.7.1/Write_your_study/Create-a-new-study.md",tags:[],version:"3.7.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:1,frontMatter:{title:"Create a new study",slug:"/Create-a-new-study.html",sidebar_position:1},sidebar:"tutorialSidebar",previous:{title:"JATOS Tryout Server",permalink:"/3.7.x/JATOS-Tryout-Server.html"},next:{title:"Write your own Study - Basics and Beyond",permalink:"/3.7.x/Write-your-own-Study-Basics-and-Beyond.html"}},u={},d=[{value:"Use a builder - OpenSesame/OSWeb and lab.js",id:"use-a-builder---opensesameosweb-and-labjs",level:3},{value:"Use jsPsych",id:"use-jspsych",level:3},{value:"Write your own study from scratch",id:"write-your-own-study-from-scratch",level:3},{value:"Modify an existing study",id:"modify-an-existing-study",level:3}],l={toc:d};function y(e){let{components:t,...r}=e;return(0,a.kt)("wrapper",(0,n.Z)({},l,r,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"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 ",(0,a.kt)("a",{parentName:"p",href:"Write-your-own-Study-Basics-and-Beyond.html"},"Write your own Study - Basics and Beyond")," or ",(0,a.kt)("a",{parentName:"p",href:"Adapt-pre-written-code-to-run-it-in-JATOS.html"},"Adapt Pre written Code to run it in JATOS"),"."),(0,a.kt)("p",null,(0,a.kt)("strong",{parentName:"p"},"Developement of a JATOS study usually happens on your local JATOS: ",(0,a.kt)("a",{parentName:"strong",href:"Run-an-experiment-with-JATOS-Workflow.html"},"Run an experiment with JATOS - Workflow"))),(0,a.kt)("h3",{id:"use-a-builder---opensesameosweb-and-labjs"},"Use a builder - OpenSesame/OSWeb and lab.js"),(0,a.kt)("p",null,"Experiment builders like ",(0,a.kt)("a",{parentName:"p",href:"OSWeb-and-JATOS.html"},"OpenSesame/OSWeb")," and ",(0,a.kt)("a",{parentName:"p",href:"labjs-and-JATOS.html"},"lab.js")," 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."),(0,a.kt)("h3",{id:"use-jspsych"},"Use jsPsych"),(0,a.kt)("p",null,(0,a.kt)("a",{parentName:"p",href:"http://www.jspsych.org/"},"jsPsych")," is a popular library for running behavioral experiments in a web browser. We have an own web page describing using ",(0,a.kt)("a",{parentName:"p",href:"jsPsych-and-JATOS.html"},"jsPsych with JATOS"),"."),(0,a.kt)("h3",{id:"write-your-own-study-from-scratch"},"Write your own study from scratch"),(0,a.kt)("p",null,"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."),(0,a.kt)("p",null,"Press the ",(0,a.kt)("strong",{parentName:"p"},"New Study")," button in the header of your local JATOS. Then edit the study properties and add new components manually. All source code for your study has to got into the study assets folder you defined in the the study properties. The study assets folder is usually located in your JATOS installation folder."),(0,a.kt)("h3",{id:"modify-an-existing-study"},"Modify an existing study"),(0,a.kt)("p",null,"Take an existing study (e.g. from ",(0,a.kt)("a",{parentName:"p",href:"/Example-Studies"},"Example Studies"),") as a prototype and modify it bit by bit. Press on the ",(0,a.kt)("strong",{parentName:"p"},"Import")," button in the header and select the file of the study. Then see the source code in your study assets folder, which is usually in your JATOS installation folder."))}y.isMDXComponent=!0}}]); \ No newline at end of file +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[5145],{3905:(e,t,r)=>{r.d(t,{Zo:()=>l,kt:()=>c});var n=r(67294);function a(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function o(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,n)}return r}function s(e){for(var t=1;t=0||(a[r]=e[r]);return a}(e,t);if(Object.getOwnPropertySymbols){var o=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(a[r]=e[r])}return a}var u=n.createContext({}),d=function(e){var t=n.useContext(u),r=t;return e&&(r="function"==typeof e?e(t):s(s({},t),e)),r},l=function(e){var t=d(e.components);return n.createElement(u.Provider,{value:t},e.children)},y={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},p=n.forwardRef((function(e,t){var r=e.components,a=e.mdxType,o=e.originalType,u=e.parentName,l=i(e,["components","mdxType","originalType","parentName"]),p=d(r),c=a,m=p["".concat(u,".").concat(c)]||p[c]||y[c]||o;return r?n.createElement(m,s(s({ref:t},l),{},{components:r})):n.createElement(m,s({ref:t},l))}));function c(e,t){var r=arguments,a=t&&t.mdxType;if("string"==typeof e||a){var o=r.length,s=new Array(o);s[0]=p;var i={};for(var u in t)hasOwnProperty.call(t,u)&&(i[u]=t[u]);i.originalType=e,i.mdxType="string"==typeof e?e:a,s[1]=i;for(var d=2;d{r.r(t),r.d(t,{assets:()=>u,contentTitle:()=>s,default:()=>y,frontMatter:()=>o,metadata:()=>i,toc:()=>d});var n=r(83117),a=(r(67294),r(3905));const o={title:"Create a new study",slug:"/Create-a-new-study.html",sidebar_position:1},s=void 0,i={unversionedId:"Write_your_study/Create-a-new-study",id:"Write_your_study/Create-a-new-study",title:"Create a new study",description:"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 or Adapt Pre written Code to run it in JATOS.",source:"@site/docs/Write_your_study/Create-a-new-study.md",sourceDirName:"Write_your_study",slug:"/Create-a-new-study.html",permalink:"/next/Create-a-new-study.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/docs/Write_your_study/Create-a-new-study.md",tags:[],version:"current",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:1,frontMatter:{title:"Create a new study",slug:"/Create-a-new-study.html",sidebar_position:1},sidebar:"tutorialSidebar",previous:{title:"JATOS Tryout Server",permalink:"/next/JATOS-Tryout-Server.html"},next:{title:"Write your own Study - Basics and Beyond",permalink:"/next/Write-your-own-Study-Basics-and-Beyond.html"}},u={},d=[{value:"Use a builder - OpenSesame/OSWeb and lab.js",id:"use-a-builder---opensesameosweb-and-labjs",level:3},{value:"Use jsPsych",id:"use-jspsych",level:3},{value:"Write your own study from scratch",id:"write-your-own-study-from-scratch",level:3},{value:"Modify an existing study",id:"modify-an-existing-study",level:3}],l={toc:d};function y(e){let{components:t,...r}=e;return(0,a.kt)("wrapper",(0,n.Z)({},l,r,{components:t,mdxType:"MDXLayout"}),(0,a.kt)("p",null,"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 ",(0,a.kt)("a",{parentName:"p",href:"Write-your-own-Study-Basics-and-Beyond.html"},"Write your own Study - Basics and Beyond")," or ",(0,a.kt)("a",{parentName:"p",href:"Adapt-pre-written-code-to-run-it-in-JATOS.html"},"Adapt Pre written Code to run it in JATOS"),"."),(0,a.kt)("p",null,(0,a.kt)("strong",{parentName:"p"},"Developement of a JATOS study usually happens on your local JATOS: ",(0,a.kt)("a",{parentName:"strong",href:"Run-an-experiment-with-JATOS-Workflow.html"},"Run an experiment with JATOS - Workflow"))),(0,a.kt)("h3",{id:"use-a-builder---opensesameosweb-and-labjs"},"Use a builder - OpenSesame/OSWeb and lab.js"),(0,a.kt)("p",null,"Experiment builders like ",(0,a.kt)("a",{parentName:"p",href:"OSWeb-and-JATOS.html"},"OpenSesame/OSWeb")," and ",(0,a.kt)("a",{parentName:"p",href:"labjs-and-JATOS.html"},"lab.js")," 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."),(0,a.kt)("h3",{id:"use-jspsych"},"Use jsPsych"),(0,a.kt)("p",null,(0,a.kt)("a",{parentName:"p",href:"http://www.jspsych.org/"},"jsPsych")," is a popular library for running behavioral experiments in a web browser. We have an own web page describing using ",(0,a.kt)("a",{parentName:"p",href:"jsPsych-and-JATOS.html"},"jsPsych with JATOS"),"."),(0,a.kt)("h3",{id:"write-your-own-study-from-scratch"},"Write your own study from scratch"),(0,a.kt)("p",null,"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."),(0,a.kt)("p",null,"Go to the study sidebar by clicking on ",(0,a.kt)("strong",{parentName:"p"},"Studies"),' in the header, top-left, then click on "',(0,a.kt)("strong",{parentName:"p"},"+"),'" and select ',(0,a.kt)("strong",{parentName:"p"},"New Study"),". Now an dialog opens where you can enter a title for the study and finally ",(0,a.kt)("strong",{parentName:"p"},"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 ",(0,a.kt)("strong",{parentName:"p"},"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."),(0,a.kt)("h3",{id:"modify-an-existing-study"},"Modify an existing study"),(0,a.kt)("p",null,"Take an existing study (e.g. from ",(0,a.kt)("a",{parentName:"p",href:"/Example-Studies"},"Example Studies"),") as a prototype and modify it bit by bit. Go to the study sidebar by clicking on ",(0,a.kt)("strong",{parentName:"p"},"Studies"),' in the header, top-left, then click on "',(0,a.kt)("strong",{parentName:"p"},"+"),'" and select ',(0,a.kt)("strong",{parentName:"p"},"Import Study"),". Then modify the source code in your ",(0,a.kt)("strong",{parentName:"p"},"study assets")," folder, which is usually in your JATOS installation folder."))}y.isMDXComponent=!0}}]); \ No newline at end of file diff --git a/assets/js/09dc4380.6586e06a.js b/assets/js/09dc4380.6586e06a.js new file mode 100644 index 000000000..ba8c659ce --- /dev/null +++ b/assets/js/09dc4380.6586e06a.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[1630],{3905:(e,t,a)=>{a.d(t,{Zo:()=>d,kt:()=>m});var n=a(67294);function r(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function s(e){for(var t=1;t=0||(r[a]=e[a]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var l=n.createContext({}),u=function(e){var t=n.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):s(s({},t),e)),a},d=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},c=n.forwardRef((function(e,t){var a=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,d=o(e,["components","mdxType","originalType","parentName"]),c=u(a),m=r,h=c["".concat(l,".").concat(m)]||c[m]||p[m]||i;return a?n.createElement(h,s(s({ref:t},d),{},{components:a})):n.createElement(h,s({ref:t},d))}));function m(e,t){var a=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=a.length,s=new Array(i);s[0]=c;var o={};for(var l in t)hasOwnProperty.call(t,l)&&(o[l]=t[l]);o.originalType=e,o.mdxType="string"==typeof e?e:r,s[1]=o;for(var u=2;u{a.r(t),a.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>p,frontMatter:()=>i,metadata:()=>o,toc:()=>u});var n=a(83117),r=(a(67294),a(3905));const i={title:"Administration",slug:"/Administration.html",sidebar_position:1},s=void 0,o={unversionedId:"Manage_your_JATOS/Administration",id:"version-3.9.1/Manage_your_JATOS/Administration",title:"Administration",description:"On the Administration page users with admin rights 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.",source:"@site/versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md",sourceDirName:"Manage_your_JATOS",slug:"/Administration.html",permalink:"/Administration.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md",tags:[],version:"3.9.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:1,frontMatter:{title:"Administration",slug:"/Administration.html",sidebar_position:1},sidebar:"tutorialSidebar",previous:{title:"Tips & tricks",permalink:"/Tips-and-Tricks.html"},next:{title:"Manage JATOS users",permalink:"/User-Manager.html"}},l={},u=[{value:"User Manager",id:"user-manager",level:3},{value:"Study Manager",id:"study-manager",level:3}],d={toc:u};function p(e){let{components:t,...i}=e;return(0,r.kt)("wrapper",(0,n.Z)({},d,i,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"On the Administration page ",(0,r.kt)("a",{parentName:"p",href:"/User-Manager.html"},"users with admin rights")," can get an overview of the studies and users of a JATOS installation. You can see the ",(0,r.kt)("strong",{parentName:"p"},"logs"),", ",(0,r.kt)("strong",{parentName:"p"},"system info"),", or go to the ",(0,r.kt)("strong",{parentName:"p"},"test page")," to check if JATOS runs correctly. It is also the place where ",(0,r.kt)("strong",{parentName:"p"},"update notifications")," appear when a new JATOS version is available and where ",(0,r.kt)("a",{parentName:"p",href:"/Update-JATOS.html#automatic-updates"},"admins can trigger an update"),"."),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Administration screenshot",src:a(17394).Z,width:"1920",height:"926"})),(0,r.kt)("h3",{id:"user-manager"},"User Manager"),(0,r.kt)("p",null,"Manage users, passwords, and rights from here. Find more details on ",(0,r.kt)("a",{parentName:"p",href:"/User-Manager.html"},"its documentation page")),(0,r.kt)("h3",{id:"study-manager"},"Study Manager"),(0,r.kt)("p",null,"By clicking the ",(0,r.kt)("strong",{parentName:"p"},"Study Manager")," 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."),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"In larger JATOS installations it can take up to a couple minutes to gather all data for this page")),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Study Manager",src:a(14098).Z,width:"1920",height:"759"})),(0,r.kt)("p",null,"The information is displayed in a table with the columns:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Active")," - In cases where e.g. a study uses to many server resources, an admin can ",(0,r.kt)("strong",{parentName:"li"},"deactivate")," (or activate again) it by clicking the switch 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."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"ID")," - The study ID"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Title")," - The study title"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Members")," - The users who are members of this study"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Study assets size")," - The disk size of all asset files associated to this study (HTML, JS, CSS, images, videos, etc.)."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Result count")," - The number of study results collected so far on this JATOS instance."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Result data size")," - The size of all result data that are stored in the database. In brackets is the average size per result count."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"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."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Last started")," - When was this study last started by a participant.")))}p.isMDXComponent=!0},17394:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/administration-25304b0246e70e52c8b58524aae3f05f.png"},14098:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/study_manager-8afadd19d1757550e2dd34e84b5d8c34.png"}}]); \ No newline at end of file diff --git a/assets/js/09dc4380.f6b91ab5.js b/assets/js/09dc4380.f6b91ab5.js deleted file mode 100644 index e1d12299e..000000000 --- a/assets/js/09dc4380.f6b91ab5.js +++ /dev/null @@ -1 +0,0 @@ -"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[1630],{3905:(e,t,a)=>{a.d(t,{Zo:()=>d,kt:()=>m});var n=a(67294);function r(e,t,a){return t in e?Object.defineProperty(e,t,{value:a,enumerable:!0,configurable:!0,writable:!0}):e[t]=a,e}function i(e,t){var a=Object.keys(e);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);t&&(n=n.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),a.push.apply(a,n)}return a}function s(e){for(var t=1;t=0||(r[a]=e[a]);return r}(e,t);if(Object.getOwnPropertySymbols){var i=Object.getOwnPropertySymbols(e);for(n=0;n=0||Object.prototype.propertyIsEnumerable.call(e,a)&&(r[a]=e[a])}return r}var l=n.createContext({}),u=function(e){var t=n.useContext(l),a=t;return e&&(a="function"==typeof e?e(t):s(s({},t),e)),a},d=function(e){var t=u(e.components);return n.createElement(l.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return n.createElement(n.Fragment,{},t)}},c=n.forwardRef((function(e,t){var a=e.components,r=e.mdxType,i=e.originalType,l=e.parentName,d=o(e,["components","mdxType","originalType","parentName"]),c=u(a),m=r,h=c["".concat(l,".").concat(m)]||c[m]||p[m]||i;return a?n.createElement(h,s(s({ref:t},d),{},{components:a})):n.createElement(h,s({ref:t},d))}));function m(e,t){var a=arguments,r=t&&t.mdxType;if("string"==typeof e||r){var i=a.length,s=new Array(i);s[0]=c;var o={};for(var l in t)hasOwnProperty.call(t,l)&&(o[l]=t[l]);o.originalType=e,o.mdxType="string"==typeof e?e:r,s[1]=o;for(var u=2;u{a.r(t),a.d(t,{assets:()=>l,contentTitle:()=>s,default:()=>p,frontMatter:()=>i,metadata:()=>o,toc:()=>u});var n=a(83117),r=(a(67294),a(3905));const i={title:"Administration",slug:"/Administration.html",sidebar_position:1},s=void 0,o={unversionedId:"Manage_your_JATOS/Administration",id:"version-3.9.1/Manage_your_JATOS/Administration",title:"Administration",description:"On the Administration page users with admin rights 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.",source:"@site/versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md",sourceDirName:"Manage_your_JATOS",slug:"/Administration.html",permalink:"/Administration.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/versioned_docs/version-3.9.1/Manage_your_JATOS/Administration.md",tags:[],version:"3.9.1",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1733302063,formattedLastUpdatedAt:"Dec 4, 2024",sidebarPosition:1,frontMatter:{title:"Administration",slug:"/Administration.html",sidebar_position:1},sidebar:"tutorialSidebar",previous:{title:"Tips & tricks",permalink:"/Tips-and-Tricks.html"},next:{title:"Manage JATOS users",permalink:"/User-Manager.html"}},l={},u=[{value:"User Manager",id:"user-manager",level:3},{value:"Study Manager",id:"study-manager",level:3}],d={toc:u};function p(e){let{components:t,...i}=e;return(0,r.kt)("wrapper",(0,n.Z)({},d,i,{components:t,mdxType:"MDXLayout"}),(0,r.kt)("p",null,"On the Administration page ",(0,r.kt)("a",{parentName:"p",href:"/User-Manager.html"},"users with admin rights")," can get an overview of the studies and users of a JATOS installation. You can see the ",(0,r.kt)("strong",{parentName:"p"},"logs"),", ",(0,r.kt)("strong",{parentName:"p"},"system info"),", or go to the ",(0,r.kt)("strong",{parentName:"p"},"test page")," to check if JATOS runs correctly. It is also the place where ",(0,r.kt)("strong",{parentName:"p"},"update notifications")," appear when a new JATOS version is available and where ",(0,r.kt)("a",{parentName:"p",href:"/Update-JATOS.html#automatic-updates"},"admins can trigger an update"),"."),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Administration screenshot",src:a(17394).Z,width:"1920",height:"926"})),(0,r.kt)("h3",{id:"user-manager"},"User Manager"),(0,r.kt)("p",null,"Manage users, passwords, and rights from here. Find more details on ",(0,r.kt)("a",{parentName:"p",href:"/User-Manager.html"},"its documentation page")),(0,r.kt)("h3",{id:"study-manager"},"Study Manager"),(0,r.kt)("p",null,"By clicking the ",(0,r.kt)("strong",{parentName:"p"},"Study Manager")," 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."),(0,r.kt)("p",null,(0,r.kt)("strong",{parentName:"p"},"In larger JATOS installations it can take up to a couple minutes to gather all data for this page")),(0,r.kt)("p",null,(0,r.kt)("img",{alt:"Study Manager",src:a(14098).Z,width:"1920",height:"759"})),(0,r.kt)("p",null,"The information is displayed in a table with the columns:"),(0,r.kt)("ul",null,(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Active")," - In cases where e.g. a study uses to many server resources, an admin can ",(0,r.kt)("strong",{parentName:"li"},"deactivate")," (or activate again) it by clicking the switch 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."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"ID")," - The study ID"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Title")," - The study title"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Members")," - The users who are members of this study"),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Study assets size")," - The disk size of all asset files associated to this study (HTML, JS, CSS, images, videos, etc.)."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Result count")," - The number of study results collected so far on this JATOS instance."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Result data size")," - The size of all result data that are stored in the database. In brackets is the average size per result count."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"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."),(0,r.kt)("li",{parentName:"ul"},(0,r.kt)("strong",{parentName:"li"},"Last started")," - When was this study last started by a participant.")))}p.isMDXComponent=!0},17394:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/administration-25304b0246e70e52c8b58524aae3f05f.png"},14098:(e,t,a)=>{a.d(t,{Z:()=>n});const n=a.p+"assets/images/study_manager-8afadd19d1757550e2dd34e84b5d8c34.png"}}]); \ No newline at end of file diff --git a/assets/js/0c7c9457.128b23f2.js b/assets/js/0c7c9457.128b23f2.js new file mode 100644 index 000000000..f197f4ac1 --- /dev/null +++ b/assets/js/0c7c9457.128b23f2.js @@ -0,0 +1 @@ +"use strict";(self.webpackChunkjatos_docs=self.webpackChunkjatos_docs||[]).push([[1249],{3905:(e,t,r)=>{r.d(t,{Zo:()=>d,kt:()=>m});var a=r(67294);function o(e,t,r){return t in e?Object.defineProperty(e,t,{value:r,enumerable:!0,configurable:!0,writable:!0}):e[t]=r,e}function n(e,t){var r=Object.keys(e);if(Object.getOwnPropertySymbols){var a=Object.getOwnPropertySymbols(e);t&&(a=a.filter((function(t){return Object.getOwnPropertyDescriptor(e,t).enumerable}))),r.push.apply(r,a)}return r}function i(e){for(var t=1;t=0||(o[r]=e[r]);return o}(e,t);if(Object.getOwnPropertySymbols){var n=Object.getOwnPropertySymbols(e);for(a=0;a=0||Object.prototype.propertyIsEnumerable.call(e,r)&&(o[r]=e[r])}return o}var l=a.createContext({}),u=function(e){var t=a.useContext(l),r=t;return e&&(r="function"==typeof e?e(t):i(i({},t),e)),r},d=function(e){var t=u(e.components);return a.createElement(l.Provider,{value:t},e.children)},p={inlineCode:"code",wrapper:function(e){var t=e.children;return a.createElement(a.Fragment,{},t)}},c=a.forwardRef((function(e,t){var r=e.components,o=e.mdxType,n=e.originalType,l=e.parentName,d=s(e,["components","mdxType","originalType","parentName"]),c=u(r),m=o,g=c["".concat(l,".").concat(m)]||c[m]||p[m]||n;return r?a.createElement(g,i(i({ref:t},d),{},{components:r})):a.createElement(g,i({ref:t},d))}));function m(e,t){var r=arguments,o=t&&t.mdxType;if("string"==typeof e||o){var n=r.length,i=new Array(n);i[0]=c;var s={};for(var l in t)hasOwnProperty.call(t,l)&&(s[l]=t[l]);s.originalType=e,s.mdxType="string"==typeof e?e:o,i[1]=s;for(var u=2;u{r.r(t),r.d(t,{assets:()=>l,contentTitle:()=>i,default:()=>p,frontMatter:()=>n,metadata:()=>s,toc:()=>u});var a=r(83117),o=(r(67294),r(3905));const n={title:"Troubleshooting",slug:"/Troubleshooting.html",sidebar_position:4},i=void 0,s={unversionedId:"Manage_your_JATOS/Troubleshooting",id:"Manage_your_JATOS/Troubleshooting",title:"Troubleshooting",description:"JATOS test page",source:"@site/docs/Manage_your_JATOS/Troubleshooting.md",sourceDirName:"Manage_your_JATOS",slug:"/Troubleshooting.html",permalink:"/next/Troubleshooting.html",draft:!1,editUrl:"https://github.com/JATOS/JATOS_docs/tree/main/docs/Manage_your_JATOS/Troubleshooting.md",tags:[],version:"current",lastUpdatedBy:"elisafilevich",lastUpdatedAt:1734681997,formattedLastUpdatedAt:"Dec 20, 2024",sidebarPosition:4,frontMatter:{title:"Troubleshooting",slug:"/Troubleshooting.html",sidebar_position:4},sidebar:"tutorialSidebar",previous:{title:"Update JATOS",permalink:"/next/Update-JATOS.html"},next:{title:"Customize JATOS' Home Page",permalink:"/next/Customize-JATOS-Home-Page.html"}},l={},u=[{value:"JATOS test page",id:"jatos-test-page",level:3},{value:"Downloading a study / exporting a study fails (e.g. in Safari browsers)",id:"downloading-a-study--exporting-a-study-fails-eg-in-safari-browsers",level:3},{value:"Read log files in the browser",id:"read-log-files-in-the-browser",level:3},{value:"A file (library, image, ...) included in the HTML fails to load?",id:"a-file-library-image--included-in-the-html-fails-to-load",level:3},{value:"Database is corrupted?",id:"database-is-corrupted",level:3}],d={toc:u};function p(e){let{components:t,...r}=e;return(0,o.kt)("wrapper",(0,a.Z)({},d,r,{components:t,mdxType:"MDXLayout"}),(0,o.kt)("h3",{id:"jatos-test-page"},"JATOS test page"),(0,o.kt)("p",null,"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 ",(0,o.kt)("em",{parentName:"p"},"Administration")," \u21d2 ",(0,o.kt)("em",{parentName:"p"},"Tests")," and check that all tests are 'OK'."),(0,o.kt)("h3",{id:"downloading-a-study--exporting-a-study-fails-eg-in-safari-browsers"},"Downloading a study / exporting a study fails (e.g. in Safari browsers)"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"https://discussions.apple.com/thread/1958374?start=0&tstart=0"},"these instructions")," to prevent Safari's automatic unzip."),(0,o.kt)("h3",{id:"read-log-files-in-the-browser"},"Read log files in the browser"),(0,o.kt)("p",null,"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 ",(0,o.kt)("a",{parentName:"p",href:"Study-Log.html"},"study log"),") to try to find what the problem might be. You can see and download all log files in the ",(0,o.kt)("em",{parentName:"p"},"Administration")," page => ",(0,o.kt)("em",{parentName:"p"},"Logs")," (for security reasons, you must be logged in as a user with admin rights). "),(0,o.kt)("ul",null,(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("em",{parentName:"li"},"application.log")," - all JATOS logging"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("em",{parentName:"li"},"loader.log")," - logging during startup with loader"),(0,o.kt)("li",{parentName:"ul"},(0,o.kt)("em",{parentName:"li"},"update.log")," - logging during updates")),(0,o.kt)("p",null,"Alternatively you can read the log files directly on the server. You'll find your logs in ",(0,o.kt)("inlineCode",{parentName:"p"},"jatos_directory/logs/"),"."),(0,o.kt)("h3",{id:"a-file-library-image--included-in-the-html-fails-to-load"},"A file (library, image, ...) included in the HTML fails to load?"),(0,o.kt)("p",null,"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. ",(0,o.kt)("inlineCode",{parentName:"p"},' - +

    JATOS

    Just Another Tool for Online Studies

    Flexible

    You can use OpenSesame, jsPsych, lab.js - or write your own experiment in JavaScipt/HTML/CSS. Get participants from Prolific or MTurk (or from wherever).

    Be in charge of your data

    JATOS is free and open source. You can install JATOS on your own server (at your university) - or in the cloud - wherever you want.

    JATOS on MindProbe

    Use this free JATOS sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    - + \ No newline at end of file diff --git a/jatos.js-Reference.html b/jatos.js-Reference.html index c373f3da6..ed7bcac99 100644 --- a/jatos.js-Reference.html +++ b/jatos.js-Reference.html @@ -10,7 +10,7 @@ - + @@ -18,8 +18,8 @@
    Version: 3.9.x

    jatos.js Reference

    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 <head> section with the following line:

    <script src="jatos.js"></script>

    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.

    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

    jatos.groupResultId​

    see Group Variables

    Study variables​

    jatos.studyProperties​

    All the properties (except the study 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 study input data you entered in the study 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 component 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 component input data you entered in the component 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/component input (in the study/component properties). 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.

    2. 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).

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

      jatos.addAbortButton()

    2. Adds a cancel button and changes some properties

      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"
      });

    3. Adds a cancel button and changes the position to the bottom-left

      jatos.addAbortButton({
        style: "left:1em; right:unset"
      });

    4. Adds a cancel button and changes the position to the top-right

      jatos.addAbortButton({
        style: "top:1em; bottom:unset"
      });

    5. Adds a cancel button and calls 'myFunction' if pressed

      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:

    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.

      jatos.showOverlay()

    2. Shows text only

      jatos.showOverlay({
        text: "Please have a coffee break for 5 minutes",
        showImg: false
      });

    3. Shows text only

      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

    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:

    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

    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. This is useful in debugging.

    Example

    jatos.catchAndLogErrors();

    jatos.addJatosIds​

    Convenience function that adds some 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

    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

    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 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, 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

    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

    2. 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

      jatos.startComponent(23);

    2. Jump to component by using its UUID

      jatos.startComponent("3d277289-754b-4fd6-aa76-c8404deda02e");

    3. Send result data and jump to another component

      var resultData = "my important result data";
      jatos.startComponent(23, resultData);

    4. Send result data, jump to another component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startComponentByPos(3);

    2. Send result data and jump to component with position 3

      var resultData = "my important result data";
      jatos.startComponentByPos(3, resultData);

    3. Send result data, jump to component in position 3 and send a message back that will be visible in JATOS result pages and log

      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

    2. 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"

      jatos.startComponentByTitle("Some title");

    2. Send result data and jump to component with title "Some title"

      var resultData = "my important result data";
      jatos.startComponentByTitle("Some title", resultData);

    3. 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 

      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

    2. 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

      jatos.startNextComponent();

    2. Send result data and jump to the next component

      var resultData = "my important result data";
      jatos.startNextComponent(resultData);

    3. Send result data, jump to the next component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startLastComponent();

    2. Send result data and jump to the last component

      var resultData = "my important result data";
      jatos.startLastComponent(resultData);

    3. Send result data, jump to the last component and send a message back that will be visible in JATOS result pages and log

      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

      jatos.abortStudy();

    2. Additionally send a message

      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, 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

      jatos.abortStudyAjax();

    2. Abort study with a message that will be sent back to JATOS and shown in the result page and put in the log

      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

    2. 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

      jatos.endStudy();

    2. End study and send a message back that will be visible in JATOS result pages and log

      jatos.endStudy(true, "everything worked fine");

    3. Indicate a failure - leads to study result state FAIL

      jatos.endStudy(false, "internal JS error");

    4. Send result data and end study

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudy(resultData);

    5. Send result data, end study and send a message back that will be visible in JATOS result pages and log

      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, 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

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    2. End study and redirect afterwards. Send result data.

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);

    3. End study and redirect afterwards. A message will be sent back to JATOS and shown in the result page and put in the log.

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", true, "everything worked fine");

    4. End study and indicate a failure and send a message. Does not redirect.

      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, 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

      jatos.endStudyAjax();

    2. End study with a message that will be sent back to JATOS and shown in the result page and put in the log

      jatos.endStudyAjax(true, "everything worked fine");

    3. Indicate a failure and send a message

      jatos.endStudyAjax(false, "some error description");

    4. End study and show the confirmation code to the MTurk worker

      jatos.endStudyAjax().then((confirmationCode) => {
        // Show the confirmation code to the worker
      });

    5. Use Promise to submit result data and afterwards, end the study and move to another URL (see also)

      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"));

    6. Send result data and end study

      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, 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

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData);

    2. 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

      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)

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData, () => { jatos.startComponentByPos(4) });

    2. Or by using the returned Promise

      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, 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

      var resultData = { "a": 123, "b": 789, "c": 100 };
      jatos.appendResultData(resultData);

    2. Use mulitple jatos.appendResultData in a row

      jatos.appendResultData({"a": 1})
         .then(() => jatos.appendResultData({"b": 2}))
         .then(() => jatos.appendResultData({"c": 3}))
         .catch(() => console.log('Something went wrong'));

    3. You can use it together with jatos.startNextComponent to first append result data and afterwards jump to the next component

      var resultData = { "a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData, jatos.startNextComponent);

    4. Or by using the returned Promise

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData)
         .then(() => jatos.startNextComponent())
         .catch(() => console.log('Something went wrong'));

    5. Or together with jatos.startComponentByPos to start a particular component (here at position 4)

      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, to signal success or failure in the transfer.

    • @param {Blob, string or object} obj - Data to be uploaded as a file. Can be 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

      jatos.uploadResultFile("this is my data", "example.txt")
         .then(() => console.log("File was successfully uploaded"))
         .catch(() => console.log("File upload failed"));

    2. Upload object as JSON

      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"));

    3. Upload text as Blob

      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"));

    4. Turn canvas into Blob and upload as image file. It assumes you have an canvas element with ID 'canvas'.

      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"));
      });

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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 are returned as a Blob. It offers callbacks, either as parameter or via a 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

      jatos.downloadResultFile("example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    2. Download JSON file

      jatos.downloadResultFile("example.json")
         .then((obj) => console.log(JSON.stringify(obj)))
         .catch(() => console.log("File download failed"));

    3. Download image and display it in a canvas element

      jatos.downloadResultFile("canvas.png")
         .then((blob) => { document.getElementById("canvas").src = URL.createObjectURL(blob) })
         .catch(() => console.log("File download failed"));

    4. Download file and specify that the file was uploaded in the first component

      jatos.downloadResultFile(1, "example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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 batch input data you entered in the batch 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). 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.

    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) and JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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

      jatos.onBatchSession(function(path, op){
        console.log("Batch Session was updated in path " + path + " with operation " + op);
      });

    2. onBatchSession is often used together with jatos.batchSession.find to get the updated value:

      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"}

      // 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

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.batchSession.set("b", "koala")
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    3. Have a series of Batch Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

      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

    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).

    • @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"}}

      jatos.batchSession.test("/a", 123); // returns true
      jatos.batchSession.test("/a", 10); // returns false
      jatos.batchSession.test("/b/b1", "flowers"); // returns true

    2. 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.

      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). 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

      jatos.batchSession.add("/a", 100);

      After the Batch Session is successfully updated the new object is {"a": 100}.

    2. Add to Batch Session

      If the Batch Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or fail

      jatos.batchSession.add("/b", 123)
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    4. Add an object:

      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.

    5. Add an array:

      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]}.

    6. Add an element to an array:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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]}.

    7. Append to the end of an array using /-:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    8. Have a series of Batch Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    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, 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

      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));
      }

    2. Example that defines the onOpen, onMemberOpen, and onMessage callbacks

      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. 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

    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

      var msg = "Message for group member 1063";
      jatos.sendGroupMsgTo("1063", msg)

    2. Use the onMemberOpen callback to send a message right after a new member opened their group channel

      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, 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

    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, 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

    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, 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

    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

    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

    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

    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

    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

    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) and broadcast messaging (jatos.sendGroupMsg) (or: more general information about the different session types).

    In difference to 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). 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.

    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) and -JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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"}

      // 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.

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

    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

    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).

    • @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"}}

      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.

      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). 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

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    - +JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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"}

      // 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.

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

    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

    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).

    • @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"}}

      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.

      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). 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

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    + \ No newline at end of file diff --git a/jsPsych-and-JATOS.html b/jsPsych-and-JATOS.html index 61806c7ca..ae3265f11 100644 --- a/jsPsych-and-JATOS.html +++ b/jsPsych-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: 3.9.x

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. 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).

      var jsPsych = initJsPsych({
        on_trial_start: jatos.addAbortButton,
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad.

      jatos.onLoad(() => {
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    - +
    Version: 3.9.x

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. 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).

      var jsPsych = initJsPsych({
        on_trial_start: jatos.addAbortButton,
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad.

      jatos.onLoad(() => {
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    + \ No newline at end of file diff --git a/labjs-and-JATOS.html b/labjs-and-JATOS.html index e95458786..bbcf067ff 100644 --- a/labjs-and-JATOS.html +++ b/labjs-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: 3.9.x

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    - +
    Version: 3.9.x

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    + \ No newline at end of file diff --git a/next/Adapt-pre-written-code-to-run-it-in-JATOS.html b/next/Adapt-pre-written-code-to-run-it-in-JATOS.html index f15778e42..fc7a37ce7 100644 --- a/next/Adapt-pre-written-code-to-run-it-in-JATOS.html +++ b/next/Adapt-pre-written-code-to-run-it-in-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Adapt pre written code to run it in JATOS

    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

    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/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. 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.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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.

    5. 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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.
    - +
    Version: next

    Adapt pre written code to run it in JATOS

    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

    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/).

    2. Copy all your files (HTML, JavaScripts, images, audio, ...) into your new study folder.

    3. 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.

    4. 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

        <script src="survey.js"></script>

        E.g. or if the file is in a subfolder 'lib'

        <script src="lib/survey.js"></script>

      2. 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'

        <script src="/study_assets/my-exp/survey.js"></script>

        ✰ 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 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.

    5. 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 <head> add the line 

      <script src="jatos.js"></script>`

    2. Add jatos.onLoad

      Most studies with JATOS start with this call. So whatever you want to do in your study it should start there.

      jatos.onLoad(function() {
        // start your code here 
      });

    3. Now to actually send your result data to JATOS we use jatos.js' function jatos.submitResultData. 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

      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.

    4. Instead of submitting text you can also upload files with jatos.uploadResultFile.

    5. At the end of your component you will want to jump to another component or end the study.

      To jump to the next component:

      jatos.startNextComponent();

      Or to just finish the study:

      jatos.endStudy();

      You can combine this with sending result data:

      jatos.startNextComponent(myResultDataObject);

      or

      jatos.endStudy(myResultDataObject);

    That's about it. Infos about other jatos.js functions and variables you can find in the reference.

    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.
    + \ No newline at end of file diff --git a/next/Administration.html b/next/Administration.html index efbde1b13..68869cc07 100644 --- a/next/Administration.html +++ b/next/Administration.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    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

    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.
    - +
    Version: next

    Administration

    On the Administration page users with admin rights 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.

    Administration screenshot

    User Manager​

    Manage users, passwords, and rights from here. Find more details on its documentation page

    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

    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.
    + \ No newline at end of file diff --git a/next/Bring-your-JATOS-online.html b/next/Bring-your-JATOS-online.html index da8838fea..324b6f31c 100644 --- a/next/Bring-your-JATOS-online.html +++ b/next/Bring-your-JATOS-online.html @@ -10,14 +10,14 @@ - +
    Version: next

    Bring your JATOS online

    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 timeSetup difficultyCostNumber of JATOS user / JATOS workers
    1. Expose your local JATOSfasteasynoneyou / few †
    2. Cloud serverfast to mediumdepends on your vendoryesmany / many ‡
    3. Own servermedium to slow (depends on your IT)needs admin skillsask your ITmany / many ‡

    †) 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

    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 or JATOS on AWS (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

    - +‡) 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

    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 or JATOS on AWS (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

    + \ No newline at end of file diff --git a/next/Change-studys-members.html b/next/Change-studys-members.html index 708ba5468..cb82013de 100644 --- a/next/Change-studys-members.html +++ b/next/Change-studys-members.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Change study's members

    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&#39;s members button

    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&#39;s members

    - +
    Version: next

    Change study's members

    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&#39;s members button

    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&#39;s members

    + \ No newline at end of file diff --git a/next/Combine-two-pre-written-studies-into-one.html b/next/Combine-two-pre-written-studies-into-one.html index cfb9512a8..247a45d41 100644 --- a/next/Combine-two-pre-written-studies-into-one.html +++ b/next/Combine-two-pre-written-studies-into-one.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Combine two pre-written studies into one

    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 and a perceptual experiment with OSWeb. 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 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.
    2. Information about where your study assets are: Go to 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.
    3. The .jzip for the first half of your study.
    4. 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 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:

    jatos.startNextComponent(myResultDataObject);

    and not 

    jatos.endStudy(myResultDataObject);
    - +
    Version: next

    Combine two pre-written studies into one

    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 and a perceptual experiment with OSWeb. 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 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.
    2. Information about where your study assets are: Go to 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.
    3. The .jzip for the first half of your study.
    4. 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 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:

    jatos.startNextComponent(myResultDataObject);

    and not 

    jatos.endStudy(myResultDataObject);
    + \ No newline at end of file diff --git a/next/Connect-to-Mechanical-Turk.html b/next/Connect-to-Mechanical-Turk.html index 27b9d2f09..2ee819a12 100644 --- a/next/Connect-to-Mechanical-Turk.html +++ b/next/Connect-to-Mechanical-Turk.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    - +
    Version: next

    Use MTurk

    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 before you let real workers do it.

    You will need​

    • A requester Mturk account
    • Your study running on a JATOS server
    • 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

    1. Don't forget to enable the MTurk type

    2. 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

    On MTurk's page​

    You first have to create a project in the MTurk interface:

    1. Sign into your MTurk requester account (or requester sandbox account)

    2. Create ⟶ New Project ⟶ Survey Link ⟶ Create Project - or just click this link for requester (or this link for requester sandbox)

    3. Complete the Enter Properties tab

    4. Click on the Design layout button in the bottom of the page.

    5. 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

    6. 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).

    7. To exit the editing mode, click on the ‘Source’ button again and continue setting up your study in MTurk.

      MTurk Schreenshot

    What should happen​

    When an MTurk worker finishes a study they'll see a confirmation code like this one.

    Confirmation code

    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

    + \ No newline at end of file diff --git a/next/Contact-us.html b/next/Contact-us.html index 7be1d8d22..1af64f907 100644 --- a/next/Contact-us.html +++ b/next/Contact-us.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    - +
    Version: next

    Contact us

    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 forum. It nucleates several cognitive science -and beyond!- tools, so we hope that this simplifies communication.

    Slack​

    Get an invite to JATOS Slack workspace.

    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.

    Google Groups​

    Google Groups

    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

    + \ No newline at end of file diff --git a/next/Create-a-new-study.html b/next/Create-a-new-study.html index ce1a0faf7..081c31eb1 100644 --- a/next/Create-a-new-study.html +++ b/next/Create-a-new-study.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Create a new study

    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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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) 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.

    - +
    Version: next

    Create a new study

    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 or Adapt Pre written Code to run it in JATOS.

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    Use a builder - OpenSesame/OSWeb and lab.js​

    Experiment builders like OpenSesame/OSWeb and lab.js 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 is a popular library for running behavioral experiments in a web browser. We have an own web page describing using jsPsych with JATOS.

    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) 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.

    + \ No newline at end of file diff --git a/next/Cross-sectional-and-longitudinal-studies.html b/next/Cross-sectional-and-longitudinal-studies.html index 435eb4ea6..03419ef5a 100644 --- a/next/Cross-sectional-and-longitudinal-studies.html +++ b/next/Cross-sectional-and-longitudinal-studies.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    - +
    Version: next

    Write cross-sectional and longitudinal studies

    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.
    2. run a between-participants study.
    3. 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 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" 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 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.

    If your sample size is relatively small and it is logistically doable, you could send individualized Personal Multiple study links 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 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.

    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

    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.

    var prolificPid = jatos.urlQueryParameters.PROLIFIC_PID;

    If you want a large sample of participants recruited outside of a marketplace (i.e. if you are using a General Multiple link, 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:

    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: 

    {
      "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: 

    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.

    + \ No newline at end of file diff --git a/next/Customize-JATOS-Home-Page.html b/next/Customize-JATOS-Home-Page.html index 911ff64ab..706736c53 100644 --- a/next/Customize-JATOS-Home-Page.html +++ b/next/Customize-JATOS-Home-Page.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Customize JATOS' Home Page

    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.

    template customized home page

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    - +
    Version: next

    Customize JATOS' Home Page

    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.

    template customized home page

    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

    2. Click 'Use this template' button to create a copy of this repository

    3. Change the content of foobar-university-welcome.html to your needs

    4. Add necessary files (e.g. logo images) to your repository

    5. 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

      2. Better use GitHub pages

        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

    6. Restart JATOS

    + \ No newline at end of file diff --git a/next/Data-Privacy-and-Ethics.html b/next/Data-Privacy-and-Ethics.html index b49d13ea3..eacd48212 100644 --- a/next/Data-Privacy-and-Ethics.html +++ b/next/Data-Privacy-and-Ethics.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Data Privacy and Ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    - +
    Version: next

    Data Privacy and Ethics

    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

    (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 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 (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 and jatos.addAbortButton that do exactly that.

    • Use encryption with your server instance. 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 JATOSIDS ( 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 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
    • 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

    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

    This cookie is used by JATOS to store which study runs with a General Single worker already happened in this browser. It only stores a list of IDs that universally identifies a study (UUID).

    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 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"

    + \ No newline at end of file diff --git a/next/Deploy-to-a-server-installation.html b/next/Deploy-to-a-server-installation.html index 0430f2e72..08ed43468 100644 --- a/next/Deploy-to-a-server-installation.html +++ b/next/Deploy-to-a-server-installation.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Deploy to a server installation

    Usually you conveniently develop your study on your local computer where you have a local installation of JATOS. Then just use the export and import buttons in your installations to transfer the study to your JATOS server.

    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 file wherever you like on your computer.
    2. 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. 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.
    - +
    Version: next

    Deploy to a server installation

    Usually you conveniently develop your study on your local computer where you have a local installation of JATOS. Then just use the export and import buttons in your installations to transfer the study to your JATOS server.

    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 file wherever you like on your computer.
    2. 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. 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.
    + \ No newline at end of file diff --git a/next/End-page-after-your-study-finished.html b/next/End-page-after-your-study-finished.html index 10e10dcaf..455e4b3e4 100644 --- a/next/End-page-after-your-study-finished.html +++ b/next/End-page-after-your-study-finished.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    End page - After your study finished

    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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    - +
    Version: next

    End page - After your study finished

    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

    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 or jatos.endStudyAjax in the JavaScript of your study's last component. This is the most versatile way.

    + \ No newline at end of file diff --git a/next/Example-Group-Studies.html b/next/Example-Group-Studies.html index c2cefd079..7545dd0a3 100644 --- a/next/Example-Group-Studies.html +++ b/next/Example-Group-Studies.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    - +
    Version: next

    Example Group Studies

    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 where exactly two workers play with each other. On the other side of the spectrum is this Snake game 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 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
    2. Open the Study Links page
    3. 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.
    4. Open a new tab in your browser and paste the study link into the address field. Press 'Enter' and the study should start.
    5. Repeat the last step to start a second Snake game.
    6. Now, in both tabs: click through the introduction until you arrive in the waiting room. Click Join and then Ready.
    7. Voilà! You'll see two snakes moving around: each tab is running the Snake Game - but they are in the same group.
    8. Optional: Have a look at your Group in the Study Links page add see who the member workers are.

    Snake example

    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.

    + \ No newline at end of file diff --git a/next/Expose-your-local-JATOS.html b/next/Expose-your-local-JATOS.html index 0844d149e..bfa7570df 100644 --- a/next/Expose-your-local-JATOS.html +++ b/next/Expose-your-local-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create study links 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.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create study links 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/.

    - +
    Version: next

    Expose your local JATOS

    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. 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.
    • 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

    ngrok​

    1. Download & setup ngrok: https://ngrok.com/download

    2. I recommend creating an account with ngrok. It's free and ngrok gives you better connection compared to without.

    3. Start your local JATOS

    4. In your terminal move to the directory where you installed ngrok and start it with:

      ./ngrok http 9000

      The output should look similar to this:

      ngrok screenshot

    5. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    6. That's all. Now you can create study links 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.

    localhost.run​

    1. Start your local JATOS

    2. Execute in your terminal

      ssh -R 80:localhost:9000 ssh.localhost.run

      E.g. the output could look like:

      $ ssh -R 80:localhost:9000 ssh.localhost.run
      Connect to http://kristian-44bs.localhost.run or https://kristian-44bs.localhost.run

    3. Copy & Paste the URL with https to your browser and check that JATOS is running properly with JATOS' build-in tests.

    4. That's all. Now you can create study links 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/.

    + \ No newline at end of file diff --git a/next/Get-started.html b/next/Get-started.html index 94f9f6e24..81f55239c 100644 --- a/next/Get-started.html +++ b/next/Get-started.html @@ -10,14 +10,14 @@ - +
    Version: next

    Get started

    Get started in 4 steps​

    1. Download JATOS and install a local instance

    2. Open JATOS' GUI by going to localhost:9000 in your browser window

    3. Download and import an example study

      1. Download one of the Example Studies, e.g. the 'Go- / No-Go Task' with jsPsych. Do not unzip the downloaded file.

      2. Import the study into JATOS: Go to JATOS' GUI in your browser and click on Import Study in the header. Choose the .jzip file you just downloaded. The imported study should appear in the sidebar on the left.

    4. 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).

      Here's a screenshot of a study's results view: -Results View screenshot

    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/.
    - +Results View screenshot

    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/next/Install-JATOS-via-Docker.html b/next/Install-JATOS-via-Docker.html index faec2c4ae..b5c7b7572 100644 --- a/next/Install-JATOS-via-Docker.html +++ b/next/Install-JATOS-via-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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 for some advanced Docker setup.

    Installation with Docker​

    1. In your terminal:

      • Get the latest release:
      docker pull jatos/jatos:latest
      • or a specific release (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    2. Run JATOS (change latest to your version)

      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.

    3. 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 - it should show the JATOS login screen
      • Check JATOS' administration page: 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

    4. Always change the admin's password after first installation: Go to 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:

    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:

    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 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):

    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 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):

    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 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:

    docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest

    Persist data with volumes​

    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:

    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:

    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, you can simply use the auto-update feature to update JATOS to newer versions.

    2. 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 - If you don't use volumes your data stored in JATOS will be lost.

    - +
    Version: next

    Install JATOS via Docker

    JATOS' Docker images are hosted at 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 for some advanced Docker setup.

    Installation with Docker​

    1. In your terminal:

      • Get the latest release:
      docker pull jatos/jatos:latest
      • or a specific release (exchange x.x.x with the version):
      docker pull jatos/jatos:x.x.x

    2. Run JATOS (change latest to your version)

      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.

    3. 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 - it should show the JATOS login screen
      • Check JATOS' administration page: 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

    4. Always change the admin's password after first installation: Go to 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:

    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:

    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 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):

    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 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):

    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 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:

    docker run -d -p 9000:9000 --volume ./jatos.conf:/opt/jatos/conf/jatos.conf:ro jatos/jatos:latest

    Persist data with volumes​

    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:

    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:

    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, you can simply use the auto-update feature to update JATOS to newer versions.

    2. 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 - If you don't use volumes your data stored in JATOS will be lost.

    + \ No newline at end of file diff --git a/next/Installation.html b/next/Installation.html index e0e89a681..2b19f5580 100644 --- a/next/Installation.html +++ b/next/Installation.html @@ -10,14 +10,14 @@ - +
    Version: next

    Installation

    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 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) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
      • Without Java: jatos.zip
      • Bundled with Java: jatos_win_java.zip
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
      • Without Java: jatos.zip
      • For MacOS bundled with Java: jatos_mac_java.zip
      • For Linux bundled with Java: jatos_linux_java.zip
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. (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.)
    6. All set! Now go to the browser of your choice and open 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 and play around with it.

    - +If you don't have Java installed, you can either download and install it (e.g. from adoptium.net) or download and install JATOS bundled with Java for your operating system.

    Installation Windows​

    1. Download the latest JATOS release
      • Without Java: jatos.zip
      • Bundled with Java: jatos_win_java.zip
    2. 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 more about why not.
    3. 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.
    4. All set! Now go to the browser of your choice and open 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
      • Without Java: jatos.zip
      • For MacOS bundled with Java: jatos_mac_java.zip
      • For Linux bundled with Java: jatos_linux_java.zip
    2. 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 more about why not.
    3. In your terminal window, cd into the unzipped JATOS folder
    4. 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'.
    5. (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.)
    6. All set! Now go to the browser of your choice and open 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 and play around with it.

    + \ No newline at end of file diff --git a/next/JATOS-API.html b/next/JATOS-API.html index c9ac60fb7..f7b38e6ec 100644 --- a/next/JATOS-API.html +++ b/next/JATOS-API.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS API

    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 in your local JATOS. (The JATOS API uses personal access tokens with bearer authentication.)
    2. Copy your token
    3. Go to petstore.swagger.io. You'll see all API endpoints and their descriptions.
    4. 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.
    5. Choose the server http://localhost:9000 (probably already set)
    6. 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. You can use petstore.swagger.io 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.

    Authentication​

    The JATOS API uses bearer authentication. It's pretty simple.

    From swagger.io:

    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 <token> with your token):

    Authorization: Bearer <token>

    And an example in different tools/languages with the endpoint /jatos/api/v1/admin/token that just returns some info about the used token:

    curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token

    Personal access tokens​

    The JATOS API uses personal access tokens (PATs or API tokens).

    From wikipedia:

    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

    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

    Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

    API token 1

    In the token overview windows you can temporarily deactivate a token or delete it altogether.

    API token 1

    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:

    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'

    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
    - +
    Version: next

    JATOS API

    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 in your local JATOS. (The JATOS API uses personal access tokens with bearer authentication.)
    2. Copy your token
    3. Go to petstore.swagger.io. You'll see all API endpoints and their descriptions.
    4. 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.
    5. Choose the server http://localhost:9000 (probably already set)
    6. 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. You can use petstore.swagger.io 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.

    Authentication​

    The JATOS API uses bearer authentication. It's pretty simple.

    From swagger.io:

    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 <token> with your token):

    Authorization: Bearer <token>

    And an example in different tools/languages with the endpoint /jatos/api/v1/admin/token that just returns some info about the used token:

    curl -i -H "Authorization: Bearer jap_OeYwru727YeLzxcHSvIFlTQ52Ud03wo7cd41f" https://example.com/jatos/api/v1/admin/token

    Personal access tokens​

    The JATOS API uses personal access tokens (PATs or API tokens).

    From wikipedia:

    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

    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

    Now your token will be shown. Copy it to a safe place. It will never be shown to you again.

    API token 1

    In the token overview windows you can temporarily deactivate a token or delete it altogether.

    API token 1

    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:

    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'

    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
    + \ No newline at end of file diff --git a/next/JATOS-Results-Archive-JRZIP.html b/next/JATOS-Results-Archive-JRZIP.html index 6e18a4a49..a28435305 100644 --- a/next/JATOS-Results-Archive-JRZIP.html +++ b/next/JATOS-Results-Archive-JRZIP.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS Results Archive (JRZIP)

    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​

    {
        "$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"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    - +
    Version: next

    JATOS Results Archive (JRZIP)

    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​

    {
        "$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"
                                                            }
                                                        }
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    + \ No newline at end of file diff --git a/next/JATOS-Study-Archive-JZIP.html b/next/JATOS-Study-Archive-JZIP.html index cb154e9d1..e1a67c4d2 100644 --- a/next/JATOS-Study-Archive-JZIP.html +++ b/next/JATOS-Study-Archive-JZIP.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS Study Archive (JZIP)

    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​

    {
        "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​

    {
        "$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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    - +
    Version: next

    JATOS Study Archive (JZIP)

    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​

    {
        "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​

    {
        "$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"
                                }
                            }
                        }
                    }
                }
            }
        }
    }
    + \ No newline at end of file diff --git a/next/JATOS-Tryout-Server.html b/next/JATOS-Tryout-Server.html index 517533d38..a9ca4ab19 100644 --- a/next/JATOS-Tryout-Server.html +++ b/next/JATOS-Tryout-Server.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    - +
    Version: next

    JATOS Tryout Server

    Cortex is a running JATOS server where you can try out JATOS in the Internet instead of your local computer:

    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.

    + \ No newline at end of file diff --git a/next/JATOS-in-Amazons-Cloud-without-Docker.html b/next/JATOS-in-Amazons-Cloud-without-Docker.html index 114f32baa..747c5357e 100644 --- a/next/JATOS-in-Amazons-Cloud-without-Docker.html +++ b/next/JATOS-in-Amazons-Cloud-without-Docker.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache 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
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    - +
    Version: next

    JATOS on AWS

    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 and applies here too. And we recommend to use JATOS together with a reverse proxy. We have instructions for Apache or Nginx. If you are looking for an easier way to install JATOS in the cloud, the tutorial JATOS on DigitalOcean might be what you are looking for.

    1. First you need to register at AWS (they'll want your credit card).
    2. In AWS webpage move to EC2 and launch a new instance with Ubuntu (you can use other Linux too)
    3. 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.
    4. 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.)
    5. 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.
    6. unzip jatos_linux_java.zip (You probably have to install 'unzip' first with sudo apt-get install unzip.)
    7. If you do not use a reverse proxy like Nginx or Apache 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
    8. Allow inbound HTTP/HTTPS traffic: This is done in AWS GUI.
    9. (Optional) auto-start JATOS
    10. Change JATOS' admin password
    + \ No newline at end of file diff --git a/next/JATOS-in-a-cluster.html b/next/JATOS-in-a-cluster.html index a78dbf54b..0cad8a8ef 100644 --- a/next/JATOS-in-a-cluster.html +++ b/next/JATOS-in-a-cluster.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS in a cluster

    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 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. 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 additionally (if you haven't already):

    1. Set -Djatos.multiNode=true in the command section of the jatos service.
    2. 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:

    docker compose -f compose.yaml up --scale jatos=2

    JATOS with Kubernetes​

    Kubernetes 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 - but with some adjustments it should work on any Kubernetes cluster.

    For the JATOS cluster we use Kustomize to define Kubernetes objects through kustomization YAML files.

    We assembled all necessary files in a git repository.

    git clone https://github.com/JATOS/JATOS_with_kubernetes.git

    The file kustomization.yaml defines our secrets and specifies the resource file, jatos.yaml, that describes the JATOS cluster.

    Then, after you set up everything, you can start the cluster with:

    kubectl apply -k <my_JATOS_kustomize_directory>

    Load-balancing and scaling​

    In our jatos.yaml, for auto-balancing in our JATOS cluster, we use the one integrated in DigitalOcean. This is specified in the Service object, with the annotation kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer".

    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%. 

    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, 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 for this purpose: nfs-server-provisioner. And since we want to run on DigitalOcean we need the parameter persistence.storageClass set to do-block-storage.

    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 the NFS storage is used in a PersistentVolumeClaim:

    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:

    volumes:
      - name: jatos-data-storage
        persistentVolumeClaim:
          claimName: jatos-data-pv-claim

    Configure JATOS' deployment​

    In 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.

    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 file and then just referenced in 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 to get started.

    In 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, a startupProbe that accounts for this. You might have to tweak failureThreshold and periodSeconds on your system.

    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 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. 

    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.

    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 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.
    2. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation.
    3. And please do backups before updating.
    - +
    Version: next

    JATOS in a cluster

    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 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. 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 additionally (if you haven't already):

    1. Set -Djatos.multiNode=true in the command section of the jatos service.
    2. 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:

    docker compose -f compose.yaml up --scale jatos=2

    JATOS with Kubernetes​

    Kubernetes 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 - but with some adjustments it should work on any Kubernetes cluster.

    For the JATOS cluster we use Kustomize to define Kubernetes objects through kustomization YAML files.

    We assembled all necessary files in a git repository.

    git clone https://github.com/JATOS/JATOS_with_kubernetes.git

    The file kustomization.yaml defines our secrets and specifies the resource file, jatos.yaml, that describes the JATOS cluster.

    Then, after you set up everything, you can start the cluster with:

    kubectl apply -k <my_JATOS_kustomize_directory>

    Load-balancing and scaling​

    In our jatos.yaml, for auto-balancing in our JATOS cluster, we use the one integrated in DigitalOcean. This is specified in the Service object, with the annotation kubernetes.digitalocean.com/load-balancer-id: "jatos-load-balancer".

    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%. 

    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, 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 for this purpose: nfs-server-provisioner. And since we want to run on DigitalOcean we need the parameter persistence.storageClass set to do-block-storage.

    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 the NFS storage is used in a PersistentVolumeClaim:

    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:

    volumes:
      - name: jatos-data-storage
        persistentVolumeClaim:
          claimName: jatos-data-pv-claim

    Configure JATOS' deployment​

    In 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.

    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 file and then just referenced in 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 to get started.

    In 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, a startupProbe that accounts for this. You might have to tweak failureThreshold and periodSeconds on your system.

    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 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. 

    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.

    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 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.
    2. JATOS is only allowed to update to higher version numbers - downgrading will likely break your installation.
    3. And please do backups before updating.
    + \ No newline at end of file diff --git a/next/JATOS-on-DigitalOcean.html b/next/JATOS-on-DigitalOcean.html index bb7a1bf53..79dde6a6b 100644 --- a/next/JATOS-on-DigitalOcean.html +++ b/next/JATOS-on-DigitalOcean.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS on DigitalOcean

    Here we explain how to install JATOS in the cloud by using DigitalOcean. 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.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Create a Droplet (this is what DigitalOcean calls a virtual machine that we want to use as a server).

    3. Choose the Region that is nearest to your users.

    4. Choose an image from Marketplace: select one with Docker on Ubuntu pre-installed.

    5. 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.

    6. Choose an authentication method

    7. Click on Advanced Options and activate Add Initialization scripts. Then copy+paste the following script in the text field:

      #!/bin/bash
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      You can change 'latest' to the specific version you need.

    8. Finally click the Create Droplet button

    9. 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.

    10. 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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source 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
    2. Set up your DNS
    3. Restart droplet
    4. 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) but in the field for the Add Initialization scripts put the following script:

    #!/bin/bash

    # Change to your email and domain (for Let's Encrypt)
    email=myemail@example.org
    domain=my.domain.org

    cat >/root/compose.yaml <<EOL
    version: "3.8"

    services:

      traefik:
        image: "traefik:v2.10"
        container_name: "traefik"
        command:
          #- "--log.level=DEBUG"
          - "--api.insecure=true"
          - "--providers.docker=true"
          - "--providers.docker.exposedbydefault=false"
          - "--entrypoints.web.address=:80"
          - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
          - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
          - "--entrypoints.websecure.address=:443"
          - "--certificatesresolvers.jatosresolver.acme.tlschallenge=true"
          #- "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
          - "--certificatesresolvers.jatosresolver.acme.email=${email}"
          - "--certificatesresolvers.jatosresolver.acme.storage=/letsencrypt/acme.json"
        ports:
          - "80:80"
          - "443:443"
        volumes:
          - "./letsencrypt:/letsencrypt"
          - "/var/run/docker.sock:/var/run/docker.sock:ro"

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        ports:
          - "9000:9000"
        volumes:
          - "jatos-logs:/opt/jatos/logs"
          - "jatos-data:/opt/jatos_data"
        labels:
          - "traefik.enable=true"
          - "traefik.http.routers.jatos.rule=Host(\`${domain}\`)"
          - "traefik.http.services.jatos.loadbalancer.server.port=9000"
          - "traefik.http.routers.jatos.entrypoints=websecure"
          - "traefik.http.routers.jatos.tls.certresolver=jatosresolver"

    volumes:
      jatos-data:
      jatos-logs:
    EOL

    docker compose -f /root/compose.yaml up -d

    This script will use Docker Compose to set up Traefik and JATOS. It creates a Docker Compose config file under /root/compose.yaml and then runs it with docker compose up.

    Before you can click the Create Droplet button, change my.domain.org and myemail@example.org (in the top of the script) with your own domain name and email address. Your email is needed to get a certificate from Let's Encrypt for encryption. Also, you might want to set JATOS version to a specific release: change latest in the line image: "jatos/jatos:latest".

    Set up your DNS​

    After you've created your Droplet, you still have to point your domain name to your server's IP address. This is what a DNS (Domain Name Service) does and it involves dealing with things like DNS records, especially A records or AAAA records, and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registrar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Restart​

    Then as a last step, after your domain name points to your server's IP, you have to restart your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and uses HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption and your domain name.

    Misc​

    • Let's Encrypt has a rate limit for the number of certificates. If you are not sure and just want to try it out, uncomment the following line in the Initialization script:

      - "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

      This will let you use their staging server that does not have such rate limit - but you won't get a proper certificate either.

    • The Docker Compose config file that is created during the Droplet initialization has the path /root/compose.yaml and the certificate is stored under /root/letsencrypt/.

    • You can configure JATOS by changing the /root/compose.yaml. You can add all command-line arguments of JATOS in the command section of the jatos service_.

      E.g. to add a welcome message on the home page use -Djatos.brandingUrl:

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.brandingUrl=https://mydomain.com/foobar-university-welcome-page.html'
          ...

      E.g. to let JATOS use an external MySQL database use -Djatos.db.url, -Djatos.db.username, -Djatos.db.password, and -Djatos.db.driver (change IP, port, username and password to the ones of your database)

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.db.url=jdbc:mysql://1.2.3.4: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'
          ...
    - +
    Version: next

    JATOS on DigitalOcean

    Here we explain how to install JATOS in the cloud by using DigitalOcean. 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.

    1. Set up an account with DigitalOcean - you'll have to provide billing information.

    2. Create a Droplet (this is what DigitalOcean calls a virtual machine that we want to use as a server).

    3. Choose the Region that is nearest to your users.

    4. Choose an image from Marketplace: select one with Docker on Ubuntu pre-installed.

    5. 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.

    6. Choose an authentication method

    7. Click on Advanced Options and activate Add Initialization scripts. Then copy+paste the following script in the text field:

      #!/bin/bash
      docker run -d --restart=always -p 80:9000 jatos/jatos:latest

      You can change 'latest' to the specific version you need.

    8. Finally click the Create Droplet button

    9. 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.

    10. 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 as a proxy. Traefik adds encryption out-of-the-box (by using Let’s Encrypt) and is open source 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
    2. Set up your DNS
    3. Restart droplet
    4. 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) but in the field for the Add Initialization scripts put the following script:

    #!/bin/bash

    # Change to your email and domain (for Let's Encrypt)
    email=myemail@example.org
    domain=my.domain.org

    cat >/root/compose.yaml <<EOL
    version: "3.8"

    services:

      traefik:
        image: "traefik:v2.10"
        container_name: "traefik"
        command:
          #- "--log.level=DEBUG"
          - "--api.insecure=true"
          - "--providers.docker=true"
          - "--providers.docker.exposedbydefault=false"
          - "--entrypoints.web.address=:80"
          - "--entrypoints.web.http.redirections.entrypoint.to=websecure"
          - "--entrypoints.web.http.redirections.entrypoint.scheme=https"
          - "--entrypoints.websecure.address=:443"
          - "--certificatesresolvers.jatosresolver.acme.tlschallenge=true"
          #- "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"
          - "--certificatesresolvers.jatosresolver.acme.email=${email}"
          - "--certificatesresolvers.jatosresolver.acme.storage=/letsencrypt/acme.json"
        ports:
          - "80:80"
          - "443:443"
        volumes:
          - "./letsencrypt:/letsencrypt"
          - "/var/run/docker.sock:/var/run/docker.sock:ro"

      jatos:
        image: "jatos/jatos:latest"
        container_name: "jatos"
        ports:
          - "9000:9000"
        volumes:
          - "jatos-logs:/opt/jatos/logs"
          - "jatos-data:/opt/jatos_data"
        labels:
          - "traefik.enable=true"
          - "traefik.http.routers.jatos.rule=Host(\`${domain}\`)"
          - "traefik.http.services.jatos.loadbalancer.server.port=9000"
          - "traefik.http.routers.jatos.entrypoints=websecure"
          - "traefik.http.routers.jatos.tls.certresolver=jatosresolver"

    volumes:
      jatos-data:
      jatos-logs:
    EOL

    docker compose -f /root/compose.yaml up -d

    This script will use Docker Compose to set up Traefik and JATOS. It creates a Docker Compose config file under /root/compose.yaml and then runs it with docker compose up.

    Before you can click the Create Droplet button, change my.domain.org and myemail@example.org (in the top of the script) with your own domain name and email address. Your email is needed to get a certificate from Let's Encrypt for encryption. Also, you might want to set JATOS version to a specific release: change latest in the line image: "jatos/jatos:latest".

    Set up your DNS​

    After you've created your Droplet, you still have to point your domain name to your server's IP address. This is what a DNS (Domain Name Service) does and it involves dealing with things like DNS records, especially A records or AAAA records, and simply can be quite annoying. You can manage your DNS settings with Digital Ocean or the registrar where you got your domain name (they will have some online help). The important thing is to put the IPv4 address of your server into the A record of your DNS settings (or if you have an IPv6 address the AAAA record). And remember, DNS changes can take from some minutes to a day to propagate throughout the Internet - So your domain name might take some time to work (you can use nslookup to check).

    Restart​

    Then as a last step, after your domain name points to your server's IP, you have to restart your server (switch off the Droplet and back on). Now Traefik requests a certificate for your domain and uses HTTPS from now on. Sometimes it's necessary to restart a second time.

    Done. You have a JATOS server with encryption and your domain name.

    Misc​

    • Let's Encrypt has a rate limit for the number of certificates. If you are not sure and just want to try it out, uncomment the following line in the Initialization script:

      - "--certificatesresolvers.jatosresolver.acme.caserver=https://acme-staging-v02.api.letsencrypt.org/directory"

      This will let you use their staging server that does not have such rate limit - but you won't get a proper certificate either.

    • The Docker Compose config file that is created during the Droplet initialization has the path /root/compose.yaml and the certificate is stored under /root/letsencrypt/.

    • You can configure JATOS by changing the /root/compose.yaml. You can add all command-line arguments of JATOS in the command section of the jatos service_.

      E.g. to add a welcome message on the home page use -Djatos.brandingUrl:

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.brandingUrl=https://mydomain.com/foobar-university-welcome-page.html'
          ...

      E.g. to let JATOS use an external MySQL database use -Djatos.db.url, -Djatos.db.username, -Djatos.db.password, and -Djatos.db.driver (change IP, port, username and password to the ones of your database)

        jatos:
          image: "jatos/jatos:latest"
          container_name: "jatos"
          command:
            - '-Djatos.db.url=jdbc:mysql://1.2.3.4: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'
          ...
    + \ No newline at end of file diff --git a/next/JATOS-on-a-server.html b/next/JATOS-on-a-server.html index 5491bf257..74fcd85b5 100644 --- a/next/JATOS-on-a-server.html +++ b/next/JATOS-on-a-server.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    And there are dedicated pages for installation with Docker and Docker Compose.

    Installing JATOS as a Internet server usually involves exchanging the embedded database with a MySQL/MariaDB one and setting up a reverse proxy (mostly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.

    Install Java​

    JATOS needs Java 8 or 11 to run (17 is not yet supported). You can install your own Java or get a JATOS that is already bundled with Java.

    Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Run JATOS:

      ./loader.sh start

      And to stop it:

      Usually Ctr+C does the job, but if your JATOS runs in the background:

      ./loader.sh stop

    5. Check JATOS is running correctly:

      Use curl: curl http://localhost:9000/ping should give you pong back

      If you can already access your server from the outside, open JATOS in a browser (the default port is 9000): http://my-IP-or-domain:9000. It should show the JATOS login screen. You can log in with username admin and password admin.

      Check JATOS' Administration page: http://my-IP-or-domain/jatos/admin. Click the Tests button: all tests should show an 'OK'. Click on System Info and check that all is like you configured it.

    6. Always change admin's password

      This can be done in JATOS' GUI:

      1. In a browser go to JATOS' login page http://my-IP-or-domain/jatos
      2. Log in as 'admin' with password 'admin'
      3. Click on Admin (admin) in top-right header
      4. Click Change Password

    [Optional] Install MySQL/MariaDB​

    See JATOS with MySQL

    Configuration​

    These docs have an extra page on JATOS Configuration. E.g. you can add user authentication with ORCID (orcid.org), OpenID Connect (OIDC), LDAP, or Google Sign-in.

    [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    [Optional] Specify the location of JATOS' data folders​

    By default all data folders are located in JATOS installation folder. But sometimes it is better to change the location to better suit your needs, e.g. for easier backups or updates.

    JATOS' data folders (and their path configuration):

    One might want to move all data folders in one extra 'data' folder. E.g. in JATOS' config file the following properties have to be set:

    jatos.studyAssetsRootPath = "/path/to/my/jatos-data-folder/study_assets_root"
    jatos.resultUploads.path =  "/path/to/my/jatos-data-folder/result_uploads"
    jatos.studyLogs.path =      "/path/to/my/jatos-data-folder/study_logs"

    Or with command-line arguments this would be:

    -Djatos.studyAssetsRootPath="/path/to/my/jatos-data-folder/study_assets_root" -Djatos.resultUploads.path="/path/to/my/jatos-data-folder/result_uploads" -Djatos.studyLogs.path="/path/to/my/jatos-data-folder/study_logs"

    [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularly.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the data folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to stop JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    1. JATOS data folders

      JATOS has a couple of data folders. For easier backups it makes sense to have them all in one extra 'data' folder. Then you can just backup this 'data' folder with whatever file backup mechanism suits you best.

    2. Backup MySQL/MariaDB

      If you use a MySQL or MariaDB database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.

    3. 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

    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.

    2. If you specified an extra 'data' folder 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.

    - +
    Version: next

    Install JATOS on a server

    There are several ways to bring JATOS to the internet. If you don't know much about server administration the DigitalOcean page might be best for you.

    And there are dedicated pages for installation with Docker and Docker Compose.

    Installing JATOS as a Internet server usually involves exchanging the embedded database with a MySQL/MariaDB one and setting up a reverse proxy (mostly for HTTPS). You should also consider automatic and regular backups of the data stored in your JATOS.

    Install Java​

    JATOS needs Java 8 or 11 to run (17 is not yet supported). You can install your own Java or get a JATOS that is already bundled with Java.

    Install JATOS​

    1. Download JATOS

      E.g. the latest release:

      wget https://github.com/JATOS/JATOS/releases/latest/download/jatos.zip

      E.g. or a certain version (exchange x.x.x with the version you want):

      wget https://github.com/JATOS/JATOS/releases/download/vx.x.x/jatos.zip

    2. JATOS comes zipped. Unpack this file at a location in your server's file system where JATOS should be installed:

      unzip jatos.zip

    3. Check that the file loader.sh in the JATOS folder is executable. If not:

      chmod u+x loader.sh

    4. Run JATOS:

      ./loader.sh start

      And to stop it:

      Usually Ctr+C does the job, but if your JATOS runs in the background:

      ./loader.sh stop

    5. Check JATOS is running correctly:

      Use curl: curl http://localhost:9000/ping should give you pong back

      If you can already access your server from the outside, open JATOS in a browser (the default port is 9000): http://my-IP-or-domain:9000. It should show the JATOS login screen. You can log in with username admin and password admin.

      Check JATOS' Administration page: http://my-IP-or-domain/jatos/admin. Click the Tests button: all tests should show an 'OK'. Click on System Info and check that all is like you configured it.

    6. Always change admin's password

      This can be done in JATOS' GUI:

      1. In a browser go to JATOS' login page http://my-IP-or-domain/jatos
      2. Log in as 'admin' with password 'admin'
      3. Click on Admin (admin) in top-right header
      4. Click Change Password

    [Optional] Install MySQL/MariaDB​

    See JATOS with MySQL

    Configuration​

    These docs have an extra page on JATOS Configuration. E.g. you can add user authentication with ORCID (orcid.org), OpenID Connect (OIDC), LDAP, or Google Sign-in.

    [Optional] Proxy and encryption​

    Most admins tend to use an additional reverse proxy in front of JATOS, mostly for encryption. We provide two example configurations for Nginx and Apache. Both support encryption and WebSockets (keep in mind JATOS relies on WebSockets and it's necessary to support them).

    [Optional] Auto-start JATOS via systemd​

    It's nice to have JATOS start automatically after a start or a reboot of your machine.

    Create a systemd service file for JATOS. E.g. with vim:

    vim /etc/systemd/system/jatos.service

    and put the following text inside (but change the JATOS path and the user under which you want to start JATOS):

    [Unit]
    Description=JATOS
    After=network-online.target
    # If you use JATOS with an MySQL database use
    #After=network-online.target mysql.service

    [Service]
    PIDFile=/my/path/to/jatos/RUNNING_PID
    User=my-jatos-user
    ExecStart=/my/path/to/jatos/loader.sh start
    ExecStop=/bin/kill $MAINPID
    ExecStopPost=/bin/rm -f /my/path/to/jatos/RUNNING_PID
    Restart=on-failure
    RestartSec=5

    [Install]
    WantedBy=multi-user.target

    Secondly, notify systemd of the new service file:

    systemctl daemon-reload

    and enable it, so it runs on boot:

    systemctl enable jatos.service

    That's it.

    Additionally you can manually start/stop JATOS now with:

    • systemctl start jatos.service
    • systemctl stop jatos.service
    • systemctl restart jatos.service
    • systemctl status jatos.service

    You can disable the service with systemctl disable jatos.service. If you change the service file you need to do systemctl daemon-reload jatos.service again to let the system know.

    [Optional] Specify the location of JATOS' data folders​

    By default all data folders are located in JATOS installation folder. But sometimes it is better to change the location to better suit your needs, e.g. for easier backups or updates.

    JATOS' data folders (and their path configuration):

    One might want to move all data folders in one extra 'data' folder. E.g. in JATOS' config file the following properties have to be set:

    jatos.studyAssetsRootPath = "/path/to/my/jatos-data-folder/study_assets_root"
    jatos.resultUploads.path =  "/path/to/my/jatos-data-folder/result_uploads"
    jatos.studyLogs.path =      "/path/to/my/jatos-data-folder/study_logs"

    Or with command-line arguments this would be:

    -Djatos.studyAssetsRootPath="/path/to/my/jatos-data-folder/study_assets_root" -Djatos.resultUploads.path="/path/to/my/jatos-data-folder/result_uploads" -Djatos.studyLogs.path="/path/to/my/jatos-data-folder/study_logs"

    [Optional] Backup​

    The easiest way to backup is to let JATOS users care themselves for their own data. JATOS has an easy to use export function for result data. So you could just tell everyone to export their data regularly.

    But if you want to set up a regular backup of the data stored in JATOS here are the necessary steps. Those data consists of several parts and all have to be backed up to be able to fully restore JATOS later.

    Simple​

    If you want to keep it simple and you didn't change any of the data folder paths then you can just back up the whole JATOS folder. But remember, if you use the embedded H2 database, to stop JATOS before doing the backup. And if you use MySQL you have to care for the MySQL backup extra.

    Detailed​

    1. JATOS data folders

      JATOS has a couple of data folders. For easier backups it makes sense to have them all in one extra 'data' folder. Then you can just backup this 'data' folder with whatever file backup mechanism suits you best.

    2. Backup MySQL/MariaDB

      If you use a MySQL or MariaDB database you might want to look into the mysqldump shell command. E.g., with mysqldump -u myusername -p mydbname > 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.

    3. 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

    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.

    2. If you specified an extra 'data' folder 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/next/JATOS-with-Apache.html b/next/JATOS-with-Apache.html index b791c7e21..f5da5a404 100644 --- a/next/JATOS-with-Apache.html +++ b/next/JATOS-with-Apache.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS with Apache

    This is an example of a configuration of Apache 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 from the Electronic Frontier Foundation.

    You have to add some modules to Apache to get it working:

    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 <Location "/jatos"> and config your local network. This will restrict the access to JATOS' GUI (every URL starting with /jatos) to the local network.

    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # 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/
    </VirtualHost>
    - +
    Version: next

    JATOS with Apache

    This is an example of a configuration of Apache 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 from the Electronic Frontier Foundation.

    You have to add some modules to Apache to get it working:

    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 <Location "/jatos"> and config your local network. This will restrict the access to JATOS' GUI (every URL starting with /jatos) to the local network.

    <VirtualHost *:80>
      ServerName www.example.com
      
      # Redirect all unencrypted traffic to the respective HTTPS page
      Redirect "/" "https://www.example.com/"
    </VirtualHost>

    <VirtualHost *:443>
      ServerName www.example.com

      # Restrict access to JATOS GUI to local network
      #<Location "/jatos">
      #  Order deny,allow
      #  Deny from all
      #  Allow from 127.0.0.1 ::1
      #  Allow from localhost
      #  Allow from 192.168
      #</Location>

      # 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/
    </VirtualHost>
    + \ No newline at end of file diff --git a/next/JATOS-with-Docker-Compose.html b/next/JATOS-with-Docker-Compose.html index 75d47ab57..0dd1543cc 100644 --- a/next/JATOS-with-Docker-Compose.html +++ b/next/JATOS-with-Docker-Compose.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS with Docker Compose

    Docker 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 that you can clone and then change them to your needs to get a JATOS installation running with docker compose. 

    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 starts three services:

    1. Nginx as a reverse proxy that does encryption (HTTPS)
    2. JATOS
    3. 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
    2. jatos-logs - for JATOS logs (not necessary if you log to stdout)
    3. jatos-db - where MySQL stores its data

    Up​

    Go into the cloned folder and start the services with:

    docker compose -f compose.yaml up

    If everything went smoothly, you will now see the JATOS login page under: 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. 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) 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 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. 

    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 with --skip-log-bin in db's command section.

    Check JATOS with MySQL for more information.

    JATOS configuration​

    Have a look at JATOS Configuration.

    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 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 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.

    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. 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.

    - +
    Version: next

    JATOS with Docker Compose

    Docker 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 that you can clone and then change them to your needs to get a JATOS installation running with docker compose. 

    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 starts three services:

    1. Nginx as a reverse proxy that does encryption (HTTPS)
    2. JATOS
    3. 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
    2. jatos-logs - for JATOS logs (not necessary if you log to stdout)
    3. jatos-db - where MySQL stores its data

    Up​

    Go into the cloned folder and start the services with:

    docker compose -f compose.yaml up

    If everything went smoothly, you will now see the JATOS login page under: 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. 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) 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 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. 

    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 with --skip-log-bin in db's command section.

    Check JATOS with MySQL for more information.

    JATOS configuration​

    Have a look at JATOS Configuration.

    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 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 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.

    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. 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.

    + \ No newline at end of file diff --git a/next/JATOS-with-MySQL.html b/next/JATOS-with-MySQL.html index ab7143a36..5bb6653ae 100644 --- a/next/JATOS-with-MySQL.html +++ b/next/JATOS-with-MySQL.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS with MySQL

    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. One way to set up MySQL:

    1. Install MySQL

      E.g. on Ubuntu

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      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.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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:

        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.

    2. 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:

        -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:

        ./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).

    3. 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:

      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):

    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.

    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). 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:

    # 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 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:

    max_allowed_packet=64M

    You have to restart the database for the changes to take effect.

    - +
    Version: next

    JATOS with MySQL

    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. One way to set up MySQL:

    1. Install MySQL

      E.g. on Ubuntu

      sudo apt install mysql-server

    2. Log in to MySQL's command line terminal:

      mysql -u root -p

    3. Create a database for JATOS:

      Character set and collation are important - otherwise you won't have full UTF-8 support

      CREATE DATABASE jatos CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

    4. Create a user for JATOS: 

      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.

    5. Grant privileges to the new user:

      GRANT ALL PRIVILEGES ON jatos.* TO 'jatosuser'@'localhost';

    6. You can test the new user: log out of MySQL with exit and back in with the newly created user:

      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:

        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.

    2. 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:

        -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:

        ./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).

    3. 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:

      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):

    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.

    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). 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:

    # 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 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:

    max_allowed_packet=64M

    You have to restart the database for the changes to take effect.

    + \ No newline at end of file diff --git a/next/JATOS-with-Nginx.html b/next/JATOS-with-Nginx.html index a3d1df55c..db7864db9 100644 --- a/next/JATOS-with-Nginx.html +++ b/next/JATOS-with-Nginx.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    JATOS with Nginx

    Here is an example for a configuration of Nginx 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 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.

    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;
            }
        }
    }
    - +
    Version: next

    JATOS with Nginx

    Here is an example for a configuration of Nginx 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 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.

    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/next/JATOS_Configuration.html b/next/JATOS_Configuration.html index dc26b1666..6bf67fa5b 100644 --- a/next/JATOS_Configuration.html +++ b/next/JATOS_Configuration.html @@ -10,14 +10,14 @@ - +
    Version: next

    JATOS Configuration

    JATOS' properties can be configured in three different ways:

    1. via a config file (named jatos.conf or production.conf)
    2. via command-line arguments
    3. 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. 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:

    ./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:

      jatos.http.address = 1.2.3.4
      jatos.http.port = 80

    2. 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:

      -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:

      play.server.http.idleTimeout = 100s

    2. Via command-line argument -Dplay.server.http.idleTimeout

      Example:

      -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:

      play.server.akka.requestTimeout = 100s

    2. Via command-line argument -Dplay.server.akka.requestTimeout

      Example:

      -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 (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:

      jatos.urlBasePath = "/mybasepath/"

    2. Via command-line arguments

      • For v3.8.1 and lower) -Dplay.http.context
      • For v3.8.2 and higher) -Djatos.urlBasePath
      -Djatos.urlBasePath="/mybasepath/"

    3. Via environment variable JATOS_URL_BASE_PATH

      JATOS_URL_BASE_PATH="/mybasepath/"

    X-Frame-Options header​

    The X-Frame-Options header can be used to allow or disallow embedding a JATOS study in an 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:

      play.filters.headers.frameOptions = null

    2. Via command-line argument -Dplay.filters.headers.frameOptions

      Example:

      -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

      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

      jatos.studyAssetsRootPath = "/path/to/my/assets/root/folder"

    2. Via command-line argument -Djatos.studyAssetsRootPath

      -Djatos.studyAssetsRootPath="/path/to/my/assets/root/folder"

    3. Via environment variable JATOS_STUDY_ASSETS_ROOT_PATH

      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

      jatos.tmpPath = "/my/tmp/dir"

    2. Via command-line argument -Djatos.tmpPath

      -Djatos.tmpPath="/my/tmp/dir"

    3. Via environment variable JATOS_TMP_PATH

      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.

    Application logs path​

    The application logs are by default in the JATOS folder under ./logs.

    1. Via config file property jatos.logs.path

      jatos.logs.path = "/my/dir/logs"

    2. Via command-line argument -Djatos.logs.path

      -Djatos.logs.path="/my/dir/logs"

    3. Via environment variable JATOS_LOGS_PATH

      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

      jatos.logs.filename = "myFilename"

    2. Via command-line argument -Djatos.logs.filename

      -Djatos.logs.filename="myFilename"

    3. Via environment variable JATOS_LOGS_FILENAME

      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

      jatos.logs.appender = ASYNCSTDOUT

    2. Via command-line argument -Djatos.logs.appender

      -Djatos.logs.appender=ASYNCSTDOUT

    3. Via environment variable JATOS_LOGS_APPENDER

      JATOS_LOGS_APPENDER=ASYNCSTDOUT

    Study logs​

    Every study stored in JATOS has its own study log (more info). 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. .

    Enable/disable study logging​

    By default study logging is enabled.

    1. Via config file property jatos.studyLogs.enabled

      jatos.studyLogs.enabled = false

    2. Via command-line argument -Djatos.studyLogs.enabled

      -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

      jatos.studyLogs.path = "/path/to/my/jatos_study_logs"

    2. Via command-line argument -Djatos.studyLogs.path

      -Djatos.studyLogs.path="/path/to/my/jatos_study_logs"

    3. Via environment variable JATOS_STUDY_LOGS_PATH

      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

      jatos.studyMembers.allowAddAllUsers = true

    2. Via command-line argument -Djatos.studyMembers.allowAddAllUsers

      -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

      jatos.maxResultsDbQuerySize = 5

    2. Via command-line argument -Djatos.maxResultsDbQuerySize

      -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

      jatos.resultData.maxSize = 10MB

    2. Via command-line argument -Djatos.resultData.maxSize

      -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

      jatos.resultUploads.enabled = false

    2. Via command-line argument -Djatos.resultUploads.enabled

      -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

      jatos.resultUploads.path = "/path/to/my/jatos_result_uploads"

    2. Via command-line argument -Djatos.resultUploads.path

      -Djatos.resultUploads.path="/path/to/my/jatos_result_uploads"

    3. Via environment variable JATOS_RESULT_UPLOADS_PATH

      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

      jatos.resultUploads.maxFileSize = 100MB

    2. Via command-line argument -Djatos.resultUploads.maxFileSize

      -Djatos.resultUploads.maxFileSize=100MB

    3. Via environment variable JATOS_RESULT_UPLOADS_MAX_FILE_SIZE

      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

      jatos.resultUploads.limitPerStudyRun = 100MB

    2. Via command-line argument -Djatos.resultUploads.limitPerStudyRun

      -Djatos.resultUploads.limitPerStudyRun=100MB

    3. Via environment variable JATOS_RESULT_UPLOADS_LIMIT_PER_STUDY_RUN

      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

      jatos.user.role.allowSuperuser = true

    2. Via command-line argument -Djatos.user.role.allowSuperuser

      -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).

    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

      jatos.user.authentication.ldap.url = "ldap://my.ldap.org:389"

    2. Via command-line argument -Djatos.user.authentication.ldap.url

      -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

      jatos.user.authentication.ldap.basedn = "dc=example,dc=com"

    2. Via command-line argument -Djatos.user.authentication.ldap.basedn

      -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

      jatos.user.authentication.ldap.admin.dn = "cn=read-only-admin,dc=example,dc=com"
      jatos.user.authentication.ldap.admin.password = "mypassword"

    2. Via command-line arguments -Djatos.user.authentication.ldap.admin.dn and -Djatos.user.authentication.ldap.admin.password

      -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

      jatos.user.authentication.ldap.timeout = 10000

    2. Via command-line argument -Djatos.user.authentication.ldap.timeout

      -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.

    1. Via config file property jatos.user.authentication.oauth.googleClientId

      jatos.user.authentication.oauth.googleClientId = "1234567890-abc123abc123.apps.googleusercontent.com"

    2. Via command-line argument -Djatos.user.authentication.oauth.googleClientId

      -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.

    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

      jatos.user.authentication.oidc.discoveryUrl = "http://myOidcProvider/.well-known/openid-configuration"

    2. Via command-line argument -Djatos.user.authentication.oidc.discoveryUrl

      -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

      jatos.user.authentication.oidc.clientId = "myClientId"

    2. Via command-line argument -Djatos.user.authentication.oidc.clientId

      -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

      jatos.user.authentication.oidc.clientSecret = "myClientSecret"

    2. Via command-line argument -Djatos.user.authentication.oidc.clientSecret

      -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

      jatos.user.authentication.oidc.idTokenSigningAlgorithm = "ES512"

    2. Via command-line argument -Djatos.user.authentication.oidc.idTokenSigningAlgorithm

      -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

      jatos.user.authentication.oidc.signInButtonText = "Sign in with ABC university"

    2. Via command-line argument -Djatos.user.authentication.oidc.signInButtonText

      -Djatos.user.authentication.oidc.signInButtonText="Sign in with ABC university"

    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

      jatos.user.authentication.oidc.signInButtonLogoUrl = "http://somedomain/logo.svg"

    2. Via command-line argument -Djatos.user.authentication.oidc.signInButtonLogoUrl

      -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

      jatos.user.authentication.oidc.successFeedback = "You successfully signed in with ABC university"

    2. Via command-line argument -Djatos.user.authentication.oidc.successFeedback

      -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. Internally ORCID uses OpenId Connect.

    ORCID client ID​

    Specifies your ORCID client ID.

    1. Via config file property jatos.user.authentication.orcid.clientId

      jatos.user.authentication.orcid.clientId = "APP-ABCDEFGHIJKLMNOP"

    2. Via command-line argument -Djatos.user.authentication.orcid.clientId

      -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

      jatos.user.authentication.orcid.clientSecret = "1234abcd-12ab-12ab-12ab-123456abcdef"

    2. Via command-line argument -Djatos.user.authentication.orcid.clientSecret

      -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

      jatos.user.password.length = 8

    2. Via command-line argument -Djatos.user.password.length

      -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

      jatos.user.password.strength = 3

    2. Via command-line argument -Djatos.user.password.strength

      -Djatos.user.password.strength=3

    Database​

    See JATOS with MySQL.

    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

      jatos.db.url = "jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"

    2. Via command-line argument -Djatos.db.url

      -Djatos.db.url="jdbc:mysql://127.0.0.1:3306/jatos?characterEncoding=UTF-8&useJDBCCompliantTimezoneShift=true&useLegacyDatetimeCode=false&serverTimezone=UTC"

    3. Via environment variable JATOS_DB_URL

      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

      jatos.db.username = "myusername"
      jatos.db.password = "mypassword"

    2. Via command-line argument -Djatos.db.username and -Djatos.db.password

      -Djatos.db.username = "myusername" -Djatos.db.password = "mypassword"

    3. Via environment variable JATOS_DB_USERNAME and JATOS_DB_PASSWORD

      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

      jatos.db.driver = "com.mysql.cj.jdbc.Driver"

    2. Via command-line argument -Djatos.db.driver

      -Djatos.db.driver="com.mysql.cj.jdbc.Driver"

    3. Via environment variable JATOS_DB_DRIVER

      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

      jatos.multiNode = true

    2. Via command-line argument -Djatos.multiNode

      -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

      jatos.userSession.timeout = 180

    2. Via command-line argument -Djatos.userSession.timeout

      -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

      jatos.userSession.inactivity = 120

    2. Via command-line argument -Djatos.userSession.inactivity

      -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

      play.http.session.secure = true

    2. Via command-line argument -Dplay.http.session.secure

      -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

      jatos.idCookies.secure = true

    2. Via command-line argument -Djatos.idCookies.secure

      -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

      jatos.idCookies.sameSite = "Lax"

    2. Via command-line argument -Djatos.idCookies.sameSite

      -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

      play.pidfile.path = "/var/run/jatos.pid"

    2. Via command-line argument -Dplay.pidfile.path

      -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). If left empty ("") the default welcome message is shown. Default is empty.

    1. Via config file property jatos.brandingUrl

      jatos.brandingUrl = "https://mydomain.com/foobar-university-welcome-page.html"

    2. Via command-line argument -Djatos.brandingUrl

      -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

      jatos.termsOfUseUrl = "https://mydomain.com/my-terms-of-use.html"

    2. Via command-line argument -Djatos.termsOfUseUrl

      -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

      jatos.studyAdmin.showStudyAssetsSize = false # Default is true
      jatos.studyAdmin.showResultDataSize = true # Default is false
      jatos.studyAdmin.showResultFileSize = true # Default is false

    2. Via command-line arguments -Djatos.studyAdmin.showStudyAssetsSize, -Djatos.studyAdmin.showResultDataSize, and -Djatos.studyAdmin.showResultFileSize

      -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

      jatos.api.allowed = false

    2. Via command-line argument -Djatos.api.allowed

      -Djatos.api.allowed = false
    - +due to a slow database or file system.

    1. Via config file properties jatos.studyAdmin.showStudyAssetsSize, jatos.studyAdmin.showResultDataSize, and jatos.studyAdmin.showResultFileSize

      jatos.studyAdmin.showStudyAssetsSize = false # Default is true
      jatos.studyAdmin.showResultDataSize = true # Default is false
      jatos.studyAdmin.showResultFileSize = true # Default is false

    2. Via command-line arguments -Djatos.studyAdmin.showStudyAssetsSize, -Djatos.studyAdmin.showResultDataSize, and -Djatos.studyAdmin.showResultFileSize

      -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

      jatos.api.allowed = false

    2. Via command-line argument -Djatos.api.allowed

      -Djatos.api.allowed = false
    + \ No newline at end of file diff --git a/next/Manage-Results.html b/next/Manage-Results.html index 7f9272a9c..fb9d37c6b 100644 --- a/next/Manage-Results.html +++ b/next/Manage-Results.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Manage Results

    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

    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

    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

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export Results​

    Results View screenshot

    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

    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).

    Export Result Data​

    Results View screenshot

    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

    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

    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

    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

    • 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.

    • 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 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 (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 or jatos.abortStudy.

    - +
    Version: next

    Manage Results

    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

    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

    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

    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

    Filter Results & Filter Builder​

    The filter lets you search all all fields in the results table (the metadata).

    Results View screenshot

    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

    Export Results​

    Results View screenshot

    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

    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).

    Export Result Data​

    Results View screenshot

    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

    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

    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

    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

    • 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.

    • 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 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 (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 or jatos.abortStudy.

    + \ No newline at end of file diff --git a/next/OSWeb-and-JATOS.html b/next/OSWeb-and-JATOS.html index dd4af9d69..2e23a2db0 100644 --- a/next/OSWeb-and-JATOS.html +++ b/next/OSWeb-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    - +
    Version: next

    OSWeb/OpenSesame and JATOS

    OSWeb lets you run an OpenSesame 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 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 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

    + \ No newline at end of file diff --git a/next/Papers-Citing-JATOS.html b/next/Papers-Citing-JATOS.html index 4f32b50bf..536f1a505 100644 --- a/next/Papers-Citing-JATOS.html +++ b/next/Papers-Citing-JATOS.html @@ -10,14 +10,14 @@ - +
    Version: next

    Papers citing JATOS

    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.)

    Please cite us 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 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

    Berkovich, R., & Meiran, N. (2024). Both pleasant and unpleasant emotional feelings follow Weber’s law but it depends how you ask. Emotion DOI

    Oz-Cohen, E., Berkovich, R. & Meiran, N. (2024) Bumpy ride ahead: Anticipated effort as emotional evidence?. Cogn Affect Behav Neurosci. DOI

    van Moorselaar, D., & Theeuwes, J. (2024). Transfer of statistical learning between tasks. Journal of Experimental Psychology: Human Perception and Performance. DOI

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Theeuwes, J., Huang, C., Frings, C., & van Moorselaar, D. (2024). Statistical learning of motor preparation. Journal of Experimental Psychology: Human Perception and Performance. DOI

    Corradi G, Aguilar P, Aguiar F, Olivera-La Rosa A (2024) Age and moral disgust: An experimental priming effects vignette study. PLoS ONE DOI

    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

    Bognar, M., Szekely, Z., Varga, M.A. et al. (2024 )Cognitive control adjustments are dependent on the level of conflict. Sci Rep DOI

    van Moorselaar D, Theeuwes J. (2024) Spatial transfer of object-based statistical learning. Atten Percept Psychophys DOI

    Lallement, C., Lemaire, P. (2024) Are There Age-Related Differences in Effects of Positive and Negative Emotions in Arithmetic? Experimental Psychology DOI

    Vandendaele, A., Prutean, N. and Declerck, M. (2024). A Blessing in Disguise: Flanking Words Can Cancel Language Switch Costs. Journal of Cognition DOI

    Moore, C.M., Zheng, Q. (2024) Limited midlevel mediation of visual crowding: Surface completion fails to support uncrowding. Journal of Vision DOI

    Oppenheim, G.M., Nozari, N. (2024) Similarity-induced interference or facilitation in language production reflects representation, not selection. Cognition DOI

    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

    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

    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

    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

    Mu, Y., Schubö, A. & Tünnermann, J. (2024) Adapting attentional control settings in a shape-changing environment. Atten Percept Psychophys. DOI

    Shyr, M.C., Joshi, S.S. (2024) A Case Study of the Validity of Web-based Visuomotor Rotation Experiments. J Cogn Neurosci DOI

    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

    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

    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

    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

    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

    Curzel, F., Carraturo, G., Ripollés, P., & Ferreri, L. (2023). Better off alone? When sharing music reduces pleasure responses. Advances in Cognitive Psychology. DOI

    Fahnenstich, H., Rieger, T., Roesler, E. (2023). Trusting under risk – comparing human to AI decision support agents. Computers in Human Behavior DOI

    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

    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

    Palmer, C. J., Kim, P., & Clifford, C. W. G. (2023). Gaze behavior as a visual cue to animacy. Journal of Experimental Psychology: General. DOI

    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

    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

    Wang, X., Li, X., Yin, Z., Wu, Y., & Liu, J. (2023). Emotional intelligence of Large Language Models. Journal of Pacific Rim Psychology. DOI

    Marks, R.A., Eggleston, R., Kovelman, I. (2023) Brain bases of morphological awareness and longitudinal word reading outcomes. Journal of Experimental Child Psychology. DOI

    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

    Oberholzer, Y., Olschewski, S., Scheibehenne, B. Complexity Aversion in Risky Choices and Valuations: Moderators and Possible Causes. Journal of Economic Psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    Vandendaele, A., & Grainger, J. (2023). Lexical competition in the flankers task revised. PLoS one DOI

    Labaronne, M., Ferreri, L. & Plancher, G. (2023) How do intentions modulate the effect of working memory on long-term memory? Psychon Bull Rev. DOI

    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

    Constant, M., Pereira, M., Faivre, N. et al. (2023) Prior information differentially affects discrimination decisions and subjective confidence reports. Nat Commun. DOI

    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

    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

    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

    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

    Sobczak, A., Bunzeck, N. (2023) Effects of positive and negative social feedback on motivation, evaluative learning, and socio-emotional processing. npj Sci. Learn. DOI

    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

    Ivanov, Y., Theeuwes, J. & Bogaerts, L. (2023) Reliability of individual differences in distractor suppression driven by statistical learning. Behav Res. DOI

    Wang-Ly, Nathan and Newell, Ben R. (2023) Uncertain goals and savings adequacy: Contrasting economic and psychological perspectives. SSRN DOI

    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

    de Waard, J., van Moorselaar, D., Bogaerts, L. et al. (2023) Statistical learning of distractor locations is dependent on task context. Sci Rep DOI

    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

    Jansen, P., Rahe, M., Hoja, S. et al. (2023) Are Character Strengths and Attitudes towards Vegetarian Food Related? Int J Appl Posit Psychol. DOI

    Kahan, T.A., Smith, Z.P. (2023) Effects of alerting signals on the spatial Stroop effect: evidence for modality differences. Psychological Research. DOI

    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

    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

    Xie, T., Fu, S. & Mento, G. (2023) Faces do not guide attention in an object-based facilitation manner. Atten Percept Psychophys. DOI

    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

    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

    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

    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

    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

    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

    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

    Gao, Y., de Waard, J. & Theeuwes, J. (2023) Learning to suppress a location is configuration-dependent. Atten Percept Psychophys DOI

    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

    Ng, D. W., Lee, J. C., & Lovibond, P. F. (2023). Unidirectional rating scales overestimate the illusory causation phenomenon. Quarterly Journal of Experimental Psychology DOI

    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

    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

    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

    Tian, J., Ren, K., Gunderson, EA. (2023) Verbal labels influence children's processing of decimal magnitudes. Journal of Applied Developmental Psychology DOI

    Bognar, M., Gyurkovics, M., van Steenbergen, H. & Aczel, B. (2023) Phasic affective signals by themselves do not regulate cognitive control. Cognition and Emotion DOI

    Huang, C., Donk, M. & Theeuwes, J. (2023) Attentional suppression is in place before display onset. Atten Percept Psychophys. DOI

    Salava, A, Salmela, V. (2023) Perceptual learning in dermatology—A Finnish cohort study of undergraduate medical students. J Eur Acad Dermatol Venereol. DOI

    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

    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

    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

    Dijkstra, N., Fleming, S.M. (2023) Subjective signal strength distinguishes reality from imagination. Nat Commun DOI

    Guseva, M., Bogler, C., Allefeld C., Haynes JD. (2023) Instruction effects on randomness in sequence generation. Frontiers in Psychology. DOI

    van Moorselaar, D., & Theeuwes, J. (2023). Statistical Learning Within Objects. Psychological Science DOI

    Lu, Z., van Zoest, W. (2023) Combining social cues in attention: Looking at gaze, head, and pointing cues. Atten Percept Psychophys. DOI

    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

    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

    Reichardt, R., Polner, B., & Simor, P. (2023). Influencing prior knowledge through a short reading impacts curiosity and learning. Applied Cognitive Psychology DOI

    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

    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

    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

    Lee, M.D., Stark, C.E.L. (2023) Bayesian modeling of the Mnemonic Similarity Task using multinomial processing trees. Behaviormetrika DOI

    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

    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

    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

    Zoefel B, Gilbert RA, Davis MH (2023) Intelligibility improves perception of timing changes in speech. PLoS ONE DOI

    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

    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

    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

    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

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys DOI

    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

    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

    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

    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

    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

    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

    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

    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

    Wittmann BC, Şatırer Y. (2022) Decreased associative processing and memory confidence in aphantasia. Learn Mem. DOI

    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

    Mueckstein, M., Heinzel, S., Granacher, U., Brahms, M., Rapp, MA., Stelzel, C. (2022) Modality-specific effects of mental fatigue in multitasking, Acta Psychologica DOI

    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

    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

    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

    Radović T, Rieger T and Manzey D (2022) A global and local perspective of interruption frequency in a visual search task. Front. Psychol. DOI

    Vos, M., Minor, S., & Ramchand, G. C. (2022). Comparing infrared and webcam eye tracking in the Visual World Paradigm. Glossa Psycholinguistics DOI

    Tsang, K. Y., & Mannion, D. J. (2022). Relating Sound and Sight in Simulated Environments. Multisensory Research DOI

    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

    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

    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

    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

    Contemori, G., Saccani, MS., Bonato, M. (2022) Multitasking Effects on Perception and Memory in Older Adults. Vision DOI

    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

    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

    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

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    - +Language Sciences DOI

    Kobzeva A, Sant C, Robbins PT, Vos M, Lohndal T, Kush D. (2022) Comparing Island Effects for Different Dependency Types in Norwegian. Languages DOI

    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

    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

    Rieger T, Manzey D. (2022) Understanding the Impact of Time Pressure and Automation Support in a Visual Search Task. Human Factors. DOI

    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

    Salava, A. and Salmela, V. (2022) Perceptual learning modules in undergraduate dermatology teaching. Clin Exp Dermatol. DOI

    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

    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

    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

    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

    Ringer, H., Schröger, E., Grimm, S. (2022) Perceptual Learning and Recognition of Random Acoustic Patterns Auditory Perception & Cognition DOI

    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

    Rahe, M., Weigelt, M., Jansen, P. Mental rotation with colored cube figures. Consciousness and Cognition DOI

    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

    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

    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

    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

    Sauter, M., Stefani, M. & Mack, W. "Equal Quality for Online and Lab Data: A Direct Comparison from Two Dual-Task Paradigms" Open Psychology DOI

    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

    Marocchini E., Domaneschi F. (2022) “Can you read my mind?” Conventionalized indirect requests and Theory of Mind abilities Journal of Pragmatics DOI

    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

    Xie, T., Fu, S. & Mento, G. (2022) Can faces affect object-based attention? Evidence from online experiments. Atten Percept Psychophys. DOI

    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

    Levinson, M., Baillet, S. (2022) Perceptual filling-in dispels the veridicality problem of conscious perception research, Consciousness and Cognition DOI

    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

    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

    Drewes, L., Nissen, V. Akzeptierte Geschäftsprozesse gestalten und implementieren. (2022) HMD DOI

    Roquet, A., Lallement, C. & Lemaire, P. Sequential modulations of emotional effects on cognitive performance in young and older adults. Motiv Emot (2022). DOI

    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

    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

    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

    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

    Gao, Y., Theeuwes, J. (2022) Learning to suppress a location does not depend on knowing which location. Atten Percept Psychophys DOI

    Dijkstra, N., Kok, P., & Fleming, S. M. (2022). Imagery adds stimulus-specific sensory evidence to perceptual detection. Journal of Vision. DOI

    Jusepeitis, A., & Rothermund, K. (2022). No elephant in the room: The incremental validity of implicit self-esteem measures. Journal of Personality. DOI

    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

    Lacassagne, D., Béna, J., Corneille, O. (2022). Is Earth a perfect square? Repetition increases the perceived truth of highly implausible statements. Cognition DOI

    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

    Scaltritti, M., Job, R. & Sulpizio, S. (2022) Different types of semantic interference, same lapses of attention: Evidence from Stroop tasks. Mem Cogn. DOI

    Zhang J, Wu Y. (2022) Epistemic reasoning in pragmatic inferencing by non-native speakers: The case of scalar implicatures. Second Language Research. DOI

    Vandendaele, A., Grainger, J. (2022). Now you see it, now you don't: Flanker presence induces the word concreteness effect. Cognition DOI.

    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

    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

    van Moorselaar, D., & Theeuwes, J. (2021). Statistical distractor learning modulates perceptual sensitivity. Journal of Vision, 21(12), 3. DOI

    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

    van Moorselaar, D., Theeuwes, J. (2021) Spatial suppression due to statistical regularities in a visual detection task. Atten Percept Psychophys. DOI

    Lallement, C. & Lemaire, P. (2021) Age-related differences in how negative emotions influence arithmetic performance, Cognition and Emotion DOI

    Mazor, M., Moran, R., Fleming, SM. (2021) Metacognitive asymmetries in visual perception, Neuroscience of Consciousness, Volume 2021, Issue 1, 2021, niab005, DOI

    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

    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

    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

    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.

    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.

    Mazor, M. & Moran, R. & Fleming, S. (2021). Metacognitive asymmetries in visual perception. Neuroscience of Consciousness. DOI.

    Meier, B. & Muhmenthaler, M. (2021). Different Impact of Perceptual Fluency and Schema Congruency on Sustainable Learning. Sustainability. 13. 7040. DOI.

    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.

    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.

    Hamami, Y., Mumma, J., Amalric, M. (2021). Counterexample Search in Diagram‐Based Geometric Reasoning. Cognitive Science. 45. DOI.

    Kobayashi, M. (2021). Replication of recall-based memory phenomena via an online experiment 再生テストに基づく記憶現象のオンライン実験による再現. The Japanese journal of psychology. DOI.

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    Richan, E., Rouat, J. A proposal and evaluation of new timbre visualization methods for audio sample browsers. Pers Ubiquit Comput (2020). DOI

    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

    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

    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

    Ren, K., & Gunderson, E. A. (2019). Malleability of whole-number and fraction biases in decimal comparison. Developmental Psychology, 55(11), 2263–2274. DOI

    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

    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

    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

    Filevich, E., Horn, S. S., & Kühn, S. (2017). Within-person adaptivity in frugal judgments from memory. Psychological Research, 1–18. DOI

    + \ No newline at end of file diff --git a/next/Restricting-study-flow.html b/next/Restricting-study-flow.html index 47e0ff0a3..081cae94a 100644 --- a/next/Restricting-study-flow.html +++ b/next/Restricting-study-flow.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Restricting study flow - reloading, linear studies, single-use workers and previews

    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

    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

    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 and about study links.

    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

    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.

    - +
    Version: next

    Restricting study flow - reloading, linear studies, single-use workers and previews

    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

    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

    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 and about study links.

    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

    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.

    + \ No newline at end of file diff --git a/next/Run-an-experiment-with-JATOS-Workflow.html b/next/Run-an-experiment-with-JATOS-Workflow.html index 457af62b5..f7cc51176 100644 --- a/next/Run-an-experiment-with-JATOS-Workflow.html +++ b/next/Run-an-experiment-with-JATOS-Workflow.html @@ -10,14 +10,14 @@ - +
    Version: next

    Run an experiment with JATOS - Workflow

    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

    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. -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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    - +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

    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.

    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.
    2. On the Study bar, click Export. A pop-up window will appear. Save the .jzip file wherever you like on your computer.
    3. On your server installation, simply click Import.

    Done.

    There are a few important details in deploying your study to a server

    Also have a look at Bring your JATOS online.

    Step 3: Collect data​

    Read about Study Links to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of worker types you need. You can (but don't have to) use MTurk or Prolific 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.

    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 to read the data into Matlab and the rjson 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.

    + \ No newline at end of file diff --git a/next/Run-your-Study-with-Study-Links.html b/next/Run-your-Study-with-Study-Links.html index e08c02a40..7c7d73862 100644 --- a/next/Run-your-Study-with-Study-Links.html +++ b/next/Run-your-Study-with-Study-Links.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Run your Study with Study Links

    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

    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

    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.

    Study Links page screenshot

    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

    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.

    Study Links page screenshot

    Personal type links can be either "Single" or "Multiple". You can find more details about them in the Worker Types 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

    1. This button creates one study link without a comment. This button is a shortcut to the "New Study Links" button.
    2. 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.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. 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).
    6. 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

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and create study links is described in its own page: Connect to Mechanical Turk.

    Study Entry Page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    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

    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

    The advantage of using the Study Entry page with the study codes is similar to a 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

    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

    • 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. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    - +
    Version: next

    Run your Study with Study Links

    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

    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

    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.

    Study Links page screenshot

    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

    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.

    Study Links page screenshot

    Personal type links can be either "Single" or "Multiple". You can find more details about them in the Worker Types 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

    1. This button creates one study link without a comment. This button is a shortcut to the "New Study Links" button.
    2. 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.
    3. This is the study code. You can hand this to your workers.
    4. 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. 2) The 'Confirm First' lets your worker confirm first with a button press. Use the button to copy the link to the clipboard or to get the QR code.
    5. 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).
    6. 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

    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.

    Study Links page screenshot

    General type links can be either Single or Multiple. You can find more details about them in the Worker Types 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

    There are two links that can be toggled by a button: 1) The 'Open Directly' link starts the study right away. 2) The 'Confirm First' lets your worker confirm first with a button press. 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.

    Study Links page screenshot

    How to connect to MTurk and create study links is described in its own page: Connect to Mechanical Turk.

    Study Entry Page​

    A study run can be started in JATOS in slightly different ways:

    1. Start directly with a study link
    2. Study link + Study Entry page for confirmation
    3. 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).

    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

    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

    The advantage of using the Study Entry page with the study codes is similar to a 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

    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

    • 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. The difference is that this one is only accessible from every study run in this batch.

    • The Group Properties relate to group studies.

    Groups​

    A batch is also the place where JATOS groups 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

    • 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 (more info).
    • 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
    + \ No newline at end of file diff --git a/next/Session-Data-Three-Types.html b/next/Session-Data-Three-Types.html index fbd2c6cd3..3dbea9e48 100644 --- a/next/Session-Data-Three-Types.html +++ b/next/Session-Data-Three-Types.html @@ -10,14 +10,14 @@ - +
    Version: next

    Session Data - Three Types

    When to use the sessions?​

    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 SessionGroup SessionStudy Session
    Scope (accesible by)All workers in a batchAll workers in a groupAll components in a study
    UsageExchange and store data relevant for all members of a batchExchange and temporarily store data relevant for all members of a groupExchange 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 batchStore choices of the two members of a Prisoner's Dilemma gamePass on correct answers between components; Keep track of the number of iterations of a given component that is repeated
    LifetimeSurvives after all workers finished their studiesAutomatically deleted once the group is finishedDeleted once the worker finished the study - Hence temporary
    Updated when and viaAny time you call one of the jatos.batchSession functionsAny time you call one of the jatos.groupSession functionsAt the end of each component or if you call jatos.setStudySessionData
    Visible and editable from JATOS' GUIyesyesno
    Requires WebSocketsyesyesno
    Included in exported studiesnonono

    Example Study​

    We have an example study, 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".

    2. Run the study once: easiest is as a JATOS worker (just click 'Run' on the study bar, not on any of the component bars).

    3. 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

    4. 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

    5. 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. 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 -Second component screenshot

    - +Second component screenshot

    + \ No newline at end of file diff --git a/next/Study-Log.html b/next/Study-Log.html index da7f15659..3a9d5718d 100644 --- a/next/Study-Log.html +++ b/next/Study-Log.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Study Log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    - +
    Version: next

    Study Log

    JATOS stores a log file for each study (not to be confused with JATOS' log 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

    Then the log looks similar to this:

    Study Log pretty

    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.
    + \ No newline at end of file diff --git a/next/Submit-and-upload-data-to-the-server.html b/next/Submit-and-upload-data-to-the-server.html index 6eb01710f..a418f659e 100644 --- a/next/Submit-and-upload-data-to-the-server.html +++ b/next/Submit-and-upload-data-to-the-server.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    - +
    Version: next

    Submit and upload data to the server

    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 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 and jatos.appendResultData 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.startComponentByPos) and all functions that end a study (jatos.endStudy and jatos.endStudyAndRedirect).

    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.

    And if you want to, in a later component, access the uploaded files again you can download them with jatos.downloadResultFile.

    For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples.

    + \ No newline at end of file diff --git a/next/Tips-and-Tricks.html b/next/Tips-and-Tricks.html index ba3fde542..edf4a5fef 100644 --- a/next/Tips-and-Tricks.html +++ b/next/Tips-and-Tricks.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Tips & Tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    - +
    Version: next

    Tips & Tricks

    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. 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, 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.

    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 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",
      });

    2. By using jatos.abortStudy 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 and Chrome's Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

    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 - 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.

    2. Allow preview - You can keep using Personal/General Single links and use a preview link to allow opening the first component of your study as many times as one wishes. All following components can be opened only once again.

    + \ No newline at end of file diff --git a/next/Troubleshooting.html b/next/Troubleshooting.html index 2c99463d6..3b12d693a 100644 --- a/next/Troubleshooting.html +++ b/next/Troubleshooting.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    - +
    Version: next

    Troubleshooting

    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 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) 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. <script src="subfolder/myscript.js"></script> and not <script src="subfolder\myscript.js"></script>.

    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 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.
    2. Don't sync while JATOS is running - As we mentioned in the Installation page, 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 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!

    + \ No newline at end of file diff --git a/next/Update-JATOS.html b/next/Update-JATOS.html index 2931eb601..a8fe05859 100644 --- a/next/Update-JATOS.html +++ b/next/Update-JATOS.html @@ -10,14 +10,14 @@ - +
    Version: next

    Update JATOS

    We'll periodically update JATOS with new features and bug fixes. We recommend you stay up to date with the latest release. 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:

    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

      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.

    2. 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

    3. After download is complete, you will be asked again for confirmation.

      Update notification Schreenshot

    4. 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.

    5. 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 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.
    2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
    3. Stop the old JATOS and start the new JATOS.
    4. 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
    2. All your studies' and components' properties
    3. The properties of the first (Default) batch

    What will be lost:

    1. All result data and files will be lost
    2. All workers in all batches (including Default batch)
    3. All batches other than the Default batch
    4. Any configuration you did in jatos.conf
    5. 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.
    2. Download and install the new version as if it were a new fresh installation. Don't start it yet.
    3. 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.
    4. Start the new JATOS.

    What will be transferred:

    1. All study assets
    2. All your study and component properties
    3. All batches, together with their workers, and generated study links
    4. All result data and files
    5. All study logs
    6. All logs
    7. JATOS' configuration (as long as it is done in the configuration file)

    What will be lost: -nothing

    - +nothing

    + \ No newline at end of file diff --git a/next/Use-Prolific.html b/next/Use-Prolific.html index 496e7091b..893795fd9 100644 --- a/next/Use-Prolific.html +++ b/next/Use-Prolific.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Use Prolific

    It is very easy to use JATOS together with Prolific 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.

    Here is a screenshot of how it looks in Prolific:

    Prolific screenshot

    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).

    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

    And copy it into the End Redirect URL field of your Study Properties in JATOS:

    screenshot

    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.

    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 in the JavaScript of your last component

    E.g. but change this URL to the one you see in Prolific

    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    You can combine it with sending result data

    var resultData = {id: 123, data: "my important result data"};
    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    - +
    Version: next

    Use Prolific

    It is very easy to use JATOS together with Prolific 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.

    Here is a screenshot of how it looks in Prolific:

    Prolific screenshot

    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).

    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

    And copy it into the End Redirect URL field of your Study Properties in JATOS:

    screenshot

    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.

    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 in the JavaScript of your last component

    E.g. but change this URL to the one you see in Prolific

    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    You can combine it with sending result data

    var resultData = {id: 123, data: "my important result data"};
    jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);
    + \ No newline at end of file diff --git a/next/User-Manager.html b/next/User-Manager.html index 905e6af90..2d9c0f032 100644 --- a/next/User-Manager.html +++ b/next/User-Manager.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Manage JATOS users

    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 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

    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

    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.

    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. 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). You can find more about how to configure JATOS to use 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. 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 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.

    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.

    - +
    Version: next

    Manage JATOS users

    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 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

    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

    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.

    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. 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). You can find more about how to configure JATOS to use 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. 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 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.

    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/next/Whats-JATOS.html b/next/Whats-JATOS.html index 4626f8f9b..f9295849d 100644 --- a/next/Whats-JATOS.html +++ b/next/Whats-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 200 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    - +
    Version: next

    What is JATOS

    JATOS (Just Another Tool for Online Studies) helps you set up and run your online studies on your own server.

    New: MindProbe, a free server for hosting online experiments. Powered by JATOS. Sponsored by the European Society for Cognitive Psychology (ESCoP) with Journal of Cognition as their official journal and OpenSesame.

    Please complete our short survey 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.

    Watch an introduction video:



    JATOS is free and open-source and released under the Apache 2 Licence. The source code is available on GitHub.

    Over 200 studies have sucessfully collected data using JATOS already! Please cite us if you use JATOS for your research.

    + \ No newline at end of file diff --git a/next/Worker-Types.html b/next/Worker-Types.html index 853b55aa8..2f6fd4a9d 100644 --- a/next/Worker-Types.html +++ b/next/Worker-Types.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Worker Types

    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.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Typical useDuring study developmentSmall targeted group, each one of them gets a linkSmall targeted group of workers who pilot the study or need to do it multiple timesBigger groups but with less control; link shared e.g. via social mediaBigger groups and where the workers need to do it multiple timesFor Amazon Mechanical Turk
    Created when?Together with the JATOS userWhen you create the linkWhen you create the linkOn-the-fly whenever someone uses the linkOn-the-fly whenever someone uses the linkOn-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
    Possible bulk creation
    Run 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). 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

    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

    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). 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

    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 page for more details on this.

    - +
    Version: next

    Worker Types

    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.

    JatosPersonal SinglePersonal MultipleGeneral SingleGeneral MultipleMTurk (Sandbox)
    Typical useDuring study developmentSmall targeted group, each one of them gets a linkSmall targeted group of workers who pilot the study or need to do it multiple timesBigger groups but with less control; link shared e.g. via social mediaBigger groups and where the workers need to do it multiple timesFor Amazon Mechanical Turk
    Created when?Together with the JATOS userWhen you create the linkWhen you create the linkOn-the-fly whenever someone uses the linkOn-the-fly whenever someone uses the linkOn-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
    Possible bulk creation
    Run 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). 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

    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

    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). 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

    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 page for more details on this.

    + \ No newline at end of file diff --git a/next/Write-Group-Studies-I-Setup.html b/next/Write-Group-Studies-I-Setup.html index cd46dbfbc..482c4e924 100644 --- a/next/Write-Group-Studies-I-Setup.html +++ b/next/Write-Group-Studies-I-Setup.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study checkbox in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 (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

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 (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 (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    - +
    Version: next

    Write Group Studies I - Setup

    Set up group studies​

    First and common to all group setups is to check the Group study checkbox in the study properties.

    Group&#39;s property

    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

    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.
    2. 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.
    3. 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 (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

    The first two scenarios may apply to the Prisoner's Dilemma Example Study.

    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 (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 (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

    Snake example

    The third and fourth scenario may apply to the Snake Example Study.

    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.

    + \ No newline at end of file diff --git a/next/Write-Group-Studies-II-JavaScript-and-Messaging.html b/next/Write-Group-Studies-II-JavaScript-and-Messaging.html index 9219a20fc..2d8d24e42 100644 --- a/next/Write-Group-Studies-II-JavaScript-and-Messaging.html +++ b/next/Write-Group-Studies-II-JavaScript-and-Messaging.html @@ -10,15 +10,15 @@ - +
    Version: next

    Write Group Studies II - JavaScript and Messaging

    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:

    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 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.

    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.

    Reassigning to a different group​

    To move a worker from one group to a different one, use jatos.reassignGroup. 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 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. Alternatively you can fix a group in JATOS' GUI, in the -Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    - +Groups table in the Study Links page.

    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 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 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 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. Members can access the Group Session data with the Group Session functions. 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, because here one dropped message would lead to important information loss.

    + \ No newline at end of file diff --git a/next/Write-your-own-Study-Basics-and-Beyond.html b/next/Write-your-own-Study-Basics-and-Beyond.html index 53b94b6ea..0f8b0bea6 100644 --- a/next/Write-your-own-Study-Basics-and-Beyond.html +++ b/next/Write-your-own-Study-Basics-and-Beyond.html @@ -10,14 +10,14 @@ - +
    Version: next

    Write your own Study - Basics and Beyond

    After you created a new study ... what comes next?

    Developement of a JATOS study usually happens on your local JATOS: Run an experiment with JATOS - Workflow

    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

    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

    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

    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

    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>
        <head>
          <script src="jatos.js"></script>
        </head>
      </html>

    2. 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.

      <script>
        jatos.onLoad(function() {
          // Start here with your code that uses jatos.js' variables and functions
        });
      </script>

    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.

    jatos.js Reference​

    In your JavaScript you will use jatos.js to handle everything JATOS related and in its reference 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

    Both input fields take JSON 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

    {
      "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.

    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, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    - +To get an idea it's best to start with examples, then one can go on to write them: Write Group Studies I - Setup and Write Group Studies II - JavaScript and Messaging.

    + \ No newline at end of file diff --git a/next/jatos.js-Reference.html b/next/jatos.js-Reference.html index 6b3ef0bf2..668892e7b 100644 --- a/next/jatos.js-Reference.html +++ b/next/jatos.js-Reference.html @@ -10,7 +10,7 @@ - + @@ -18,8 +18,8 @@
    Version: next

    jatos.js Reference

    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 <head> section with the following line:

    <script src="jatos.js"></script>

    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.

    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

    jatos.groupResultId​

    see 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.

    2. 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).

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

      jatos.addAbortButton()

    2. Adds a cancel button and changes some properties

      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"
      });

    3. Adds a cancel button and changes the position to the bottom-left

      jatos.addAbortButton({
        style: "left:1em; right:unset"
      });

    4. Adds a cancel button and changes the position to the top-right

      jatos.addAbortButton({
        style: "top:1em; bottom:unset"
      });

    5. Adds a cancel button and calls 'myFunction' if pressed

      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:

    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.

      jatos.showOverlay()

    2. Shows text only

      jatos.showOverlay({
        text: "Please have a coffee break for 5 minutes",
        showImg: false
      });

    3. Shows text only

      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

    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:

    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

    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. This is useful in debugging.

    Example

    jatos.catchAndLogErrors();

    jatos.addJatosIds​

    Convenience function that adds some 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

    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

    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 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, 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

    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

    2. 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

      jatos.startComponent(23);

    2. Jump to component by using its UUID

      jatos.startComponent("3d277289-754b-4fd6-aa76-c8404deda02e");

    3. Send result data and jump to another component

      var resultData = "my important result data";
      jatos.startComponent(23, resultData);

    4. Send result data, jump to another component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startComponentByPos(3);

    2. Send result data and jump to component with position 3

      var resultData = "my important result data";
      jatos.startComponentByPos(3, resultData);

    3. Send result data, jump to component in position 3 and send a message back that will be visible in JATOS result pages and log

      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

    2. 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"

      jatos.startComponentByTitle("Some title");

    2. Send result data and jump to component with title "Some title"

      var resultData = "my important result data";
      jatos.startComponentByTitle("Some title", resultData);

    3. 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 

      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

    2. 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

      jatos.startNextComponent();

    2. Send result data and jump to the next component

      var resultData = "my important result data";
      jatos.startNextComponent(resultData);

    3. Send result data, jump to the next component and send a message back that will be visible in JATOS result pages and log

      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

    2. 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

      jatos.startLastComponent();

    2. Send result data and jump to the last component

      var resultData = "my important result data";
      jatos.startLastComponent(resultData);

    3. Send result data, jump to the last component and send a message back that will be visible in JATOS result pages and log

      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

      jatos.abortStudy();

    2. Additionally send a message

      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, 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

      jatos.abortStudyAjax();

    2. Abort study with a message that will be sent back to JATOS and shown in the result page and put in the log

      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

    2. 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

      jatos.endStudy();

    2. End study and send a message back that will be visible in JATOS result pages and log

      jatos.endStudy(true, "everything worked fine");

    3. Indicate a failure - leads to study result state FAIL

      jatos.endStudy(false, "internal JS error");

    4. Send result data and end study

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudy(resultData);

    5. Send result data, end study and send a message back that will be visible in JATOS result pages and log

      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, 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

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD");

    2. End study and redirect afterwards. Send result data.

      var resultData = {id: 123, data: "my important result data"};
      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", resultData);

    3. End study and redirect afterwards. A message will be sent back to JATOS and shown in the result page and put in the log.

      jatos.endStudyAndRedirect("https://app.prolific.co/submissions/complete?cc=1234ABCD", true, "everything worked fine");

    4. End study and indicate a failure and send a message. Does not redirect.

      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, 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

      jatos.endStudyAjax();

    2. End study with a message that will be sent back to JATOS and shown in the result page and put in the log

      jatos.endStudyAjax(true, "everything worked fine");

    3. Indicate a failure and send a message

      jatos.endStudyAjax(false, "some error description");

    4. End study and show the confirmation code to the MTurk worker

      jatos.endStudyAjax().then((confirmationCode) => {
        // Show the confirmation code to the worker
      });

    5. Use Promise to submit result data and afterwards, end the study and move to another URL (see also)

      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"));

    6. Send result data and end study

      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, 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

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData);

    2. 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

      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)

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.submitResultData(resultData, () => { jatos.startComponentByPos(4) });

    2. Or by using the returned Promise

      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, 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

      var resultData = { "a": 123, "b": 789, "c": 100 };
      jatos.appendResultData(resultData);

    2. Use mulitple jatos.appendResultData in a row

      jatos.appendResultData({"a": 1})
         .then(() => jatos.appendResultData({"b": 2}))
         .then(() => jatos.appendResultData({"c": 3}))
         .catch(() => console.log('Something went wrong'));

    3. You can use it together with jatos.startNextComponent to first append result data and afterwards jump to the next component

      var resultData = { "a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData, jatos.startNextComponent);

    4. Or by using the returned Promise

      var resultData = {"a": 123, "b": 789, "c": 100};
      jatos.appendResultData(resultData)
         .then(() => jatos.startNextComponent())
         .catch(() => console.log('Something went wrong'));

    5. Or together with jatos.startComponentByPos to start a particular component (here at position 4)

      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, to signal success or failure in the transfer.

    • @param {Blob, string or object} obj - Data to be uploaded as a file. Can be 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

      jatos.uploadResultFile("this is my data", "example.txt")
         .then(() => console.log("File was successfully uploaded"))
         .catch(() => console.log("File upload failed"));

    2. Upload object as JSON

      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"));

    3. Upload text as Blob

      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"));

    4. Turn canvas into Blob and upload as image file. It assumes you have an canvas element with ID 'canvas'.

      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"));
      });

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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 are returned as a Blob. It offers callbacks, either as parameter or via a 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

      jatos.downloadResultFile("example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    2. Download JSON file

      jatos.downloadResultFile("example.json")
         .then((obj) => console.log(JSON.stringify(obj)))
         .catch(() => console.log("File download failed"));

    3. Download image and display it in a canvas element

      jatos.downloadResultFile("canvas.png")
         .then((blob) => { document.getElementById("canvas").src = URL.createObjectURL(blob) })
         .catch(() => console.log("File download failed"));

    4. Download file and specify that the file was uploaded in the first component

      jatos.downloadResultFile(1, "example.txt")
         .then((text) => console.log(text))
         .catch(() => console.log("File download failed"));

    5. For more real-world examples have a look at the 'Drawing' and the 'Video Recording' examples

    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). 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.

    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) and JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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

      jatos.onBatchSession(function(path, op){
        console.log("Batch Session was updated in path " + path + " with operation " + op);
      });

    2. onBatchSession is often used together with jatos.batchSession.find to get the updated value:

      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"}

      // 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

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.batchSession.set("b", "koala")
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    3. Have a series of Batch Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

      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

    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).

    • @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"}}

      jatos.batchSession.test("/a", 123); // returns true
      jatos.batchSession.test("/a", 10); // returns false
      jatos.batchSession.test("/b/b1", "flowers"); // returns true

    2. 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.

      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). 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

      jatos.batchSession.add("/a", 100);

      After the Batch Session is successfully updated the new object is {"a": 100}.

    2. Add to Batch Session

      If the Batch Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or fail

      jatos.batchSession.add("/b", 123)
         .then(() => console.log("Batch Session was successfully updated"))
         .catch(() => console.log("Batch Session synchronization failed"));

    4. Add an object:

      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.

    5. Add an array:

      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]}.

    6. Add an element to an array:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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]}.

    7. Append to the end of an array using /-:

      If the Batch Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    8. Have a series of Batch Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    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, 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

      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));
      }

    2. Example that defines the onOpen, onMemberOpen, and onMessage callbacks

      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. 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

    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

      var msg = "Message for group member 1063";
      jatos.sendGroupMsgTo("1063", msg)

    2. Use the onMemberOpen callback to send a message right after a new member opened their group channel

      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, 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

    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, 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

    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, 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

    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

    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

    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

    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

    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

    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) and broadcast messaging (jatos.sendGroupMsg) (or: more general information about the different session types).

    In difference to 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). 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.

    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) and -JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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"}

      // 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.

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

    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

    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).

    • @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"}}

      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.

      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). 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

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    - +JSON Pointer (RFC 6901). An introduction can be found under jsonpatch.com. For JSON Patches jatos.js uses the JSON-Patch library from Joachim Wester and for JSON Pointers the 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"}

      // 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.

    2. 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"}}

      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}

      // 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.

    2. Use returned Promise to handle success or failure

      jatos.groupSession.set("b", "koala")
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    3. Have a series of Group Session changes

      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

    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

      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.

    2. Use returned Promise to handle success or failure

      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

      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.

    2. Use returned Promise to handle success or failure

      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}

    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

    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).

    • @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"}}

      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.

      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). 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

      jatos.groupSession.add("/a", 100);

      After the Group Session is successfully updated the new object is {"a": 100}.

    2. Add an a field to the Group Session

      If the Group Session is {"a": 100} and one calls

      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.

    3. Use returned Promise to handle success or failure

      jatos.groupSession.add("/b", 123)
         .then(() => console.log("Group Session was successfully updated"))
         .catch(() => console.log("Group Session synchronization failed"));

    4. Add an object:

      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"}}.

    5. Add to a nested object:

      If the Group Session is {"a": {"b": {}}} and one calls

      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.

    6. Add an array:

      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]}.

    7. Add an element to an array:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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]}.

    8. Append to the end of an array using /-:

      If the Group Session is {"array": [1, 2, 3]} and one calls

      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"]}.

    9. Have a series of Group Session updates

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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).

    • @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

      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.

    2. Use returned Promise to handle success or failure

      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

    jatos.groupSessionVersioning = false; // Turns off versioning
    + \ No newline at end of file diff --git a/next/jsPsych-and-JATOS.html b/next/jsPsych-and-JATOS.html index 9b2e04c72..1cd7b71ae 100644 --- a/next/jsPsych-and-JATOS.html +++ b/next/jsPsych-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. 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).

      var jsPsych = initJsPsych({
        on_trial_start: jatos.addAbortButton,
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad.

      jatos.onLoad(() => {
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    - +
    Version: next

    jsPsych and JATOS

    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.

    In our 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.

    Every jsPsych version works slightly different. Here we explain the steps for jsPsych 7 (for older versions have a look here).

    How to turn your jsPsych 7 experiment into a JATOS study​

    1. Include the jatos.js library in the <head> of your HTML

      <script src="jatos.js"></script>

    2. 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).

      var jsPsych = initJsPsych({
        on_trial_start: jatos.addAbortButton,
        on_finish: () => jatos.endStudy(jsPsych.data.get().json())
      });

    3. Wrap jsPsych's run in jatos.onLoad.

      jatos.onLoad(() => {
        jsPsych.run(timeline);
      });

    That's all. Have a look at the 'Simple Reaction Time Task' in our example studies to see a full example with jsPsych 7.

    + \ No newline at end of file diff --git a/next/labjs-and-JATOS.html b/next/labjs-and-JATOS.html index 751ba66f0..d44e3f054 100644 --- a/next/labjs-and-JATOS.html +++ b/next/labjs-and-JATOS.html @@ -10,13 +10,13 @@ - +
    -
    Version: next

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    - +
    Version: next

    lab.js and JATOS

    lab.js is an easy to use tool to create online experiments. Their builder 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 and one page there is solely dedicated to JATOS: Collecting data with JATOS.

    That's all there is to say.

    + \ No newline at end of file