Skip to content

Commit

Permalink
Change 'create' to 'add'
Browse files Browse the repository at this point in the history
  • Loading branch information
kristian-lange committed Jun 6, 2024
1 parent c06772a commit 51ff813
Show file tree
Hide file tree
Showing 12 changed files with 29 additions and 29 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -32,19 +32,19 @@ You can either tell JATOS to assign workers to different groups, or you can keep

### Scenario 1: One group, assign workers manually

If in a batch you set the _Max total worker_ to 2 and leave the other two Max parameters empty, JATOS has no other choice than to allow only 2 workers and sort them into the same group. If you then [create two Personal Single study links](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send the links to your two participants, you can be sure that they will interact with each other. If you need more groups, just create a second batch with two other workers.
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](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send the links to your two participants, you can be sure that they will interact with each other. If you need more groups, just add a second batch with two other workers.

![Prisoners example](/img/prisoners_example.png)

The first two scenarios may apply to the [Prisoner's Dilemma Example Study](/Example-Studies).

### Scenario 2: Several groups, let JATOS assign workers

Say you want to have 3 groups with 2 workers each. You want to leave it to JATOS which workers are paired together. Then, set _Max total workers_ to 6 and both _Max active members_ and _Max total members_ to 2 (remember that these numbers apply to each group separately). Then [create 6 Personal Single study links](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send them to your 6 participants.
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](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and send them to your 6 participants.

### Scenario 3: One open world

This scenario is basically the opposite of the first one. By limiting neither the _Max total worker_ nor the _Max total members_, nor the _Max active members_ JATOS will sort all workers into one single group that is potentially of unlimited size. Now --to keep it completely open-- just [create one study link type General Single](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).
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](Run-your-Study-with-Study-Links.html) (but other study link types are fine too) and publish it (e.g. via a mailing list or on a website).

![Snake example](/img/snake_example.png)

Expand Down
14 changes: 7 additions & 7 deletions versioned_docs/version-3.9.1/Manage_your_JATOS/User-Manager.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@ slug: /User-Manager.html
sidebar_position: 2
---

Each experimenter with access to the JATOS server (though the GUI) is a JATOS User. Users can create, modify and delete the studies they are members of. They can also export and delete results. Users may also have special roles: **Admin** or **Superusers**. Only Admin users have access to the [_Administration_ page](Administration.html) and control other users' access to JATOS. Superusers exist only since JATOS version 3.7.4 and they can access all studies on this JATOS including their result data.
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](Administration.html) and control other users' access to JATOS. Superusers exist only since JATOS version 3.7.4 and they can access all studies on this JATOS including their result data.


## Manage users

Only users with admin rights have access to the **User Manager** (in the _Administration_ page). From the _User Manager_, admins can create new users or delete existing ones, or change passwords. Admins can also deactivate/activate users and see information about the user's studies.
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!

Expand Down Expand Up @@ -43,9 +43,9 @@ Superusers can access all studies on this JATOS instance regardless if they were

JATOS allows password authentication via LDAP (which lets an institution manage their users in a centralized way). LDAP is disabled by default. To enable it [change the JATOS config file](JATOS_Configuration.html#ldap-authentication).

Once LDAP is enabled, there will be an additional switch '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.
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 create LDAP users automatically - they must be created by an JATOS admin manually.
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
Expand All @@ -56,14 +56,14 @@ Google Sign-In is deactivated by default and can be activated by adding your Goo
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.
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](https://openid.net/developers/how-connect-works/). OIDC is an authentication protocol that offers an easy-to-use sign in button. It needs an OIDC provider that is not part of JATOS (e.g. [Keycloak](https://www.keycloak.org/)). You can find more about [how to configure JATOS to use OIDC](/JATOS_Configuration.html#openid-connect-oidc) in the JATOS configuration page.

If a new user authenticates the first time with OIDC the user will be automatically created in JATOS. This means an OIDC user cannot be created by a JATOS Admin.
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)
Expand All @@ -72,4 +72,4 @@ Since version 3.8.5 JATOS users can be authenticated by [ORCID sign-in](https://

You only need to set two parameters in JATOS' configuration to make your JATOS use ORCID's authentication: your ORCID _client ID_ and _client secret_. Read [here](https://info.orcid.org/documentation/integration-guide/registering-a-public-api-client/) more about how to get these (but the short version is: Go to your ORCID user page -> expand your username top right: click _Developer Tools_). Then [configure your JATOS with your client ID and secret](/JATOS_Configuration.html#orcid-orcidorg-authentication).

If a new user authenticates the first time with ORCID the user will be automatically created in JATOS. This means an ORCID user cannot be created by a JATOS Admin.
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.
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ There are a few important details in [deploying your study to a server](Deploy-t
Also have a look at [Bring your JATOS online](Bring-your-JATOS-online.html).

## Step 3: Collect data
Read about [Study Links](Run-your-Study-with-Study-Links.html) to create links that you can distribute to your participants. You can do this in many different ways, decide which kind of [worker types](Worker-Types.html) you need. You can (but don't have to) use [MTurk](Connect-to-Mechanical-Turk.html) or [Prolific](Use-Prolific.html) to get participants.
Read about [Study Links](Run-your-Study-with-Study-Links.html) to add links that you can distribute to your participants. You can do this in many different ways, decide which kind of [worker types](Worker-Types.html) you need. You can (but don't have to) use [MTurk](Connect-to-Mechanical-Turk.html) or [Prolific](Use-Prolific.html) to get participants.

## Step 4: Download and analyze data
One of JATOS' features is that you can manage the results stored in the database without having to type SQL commands in a terminal. Instead, just do this [using the GUI](Manage-Results.html).
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -130,7 +130,7 @@ The JATOS API uses personal access tokens (PATs or API tokens).

From [wikipedia](https://en.wikipedia.org/wiki/Personal_access_token):

> a personal access token (or PAT) is a string of characters that can be used to authenticate a user when accessing a computer system instead of the usual password. Though associated with a single account, multiple PATs may be created, and can be manipulated independently of the password associated with that account, including creation and revocation of PATs without altering the password.
> 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.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -489,7 +489,7 @@ If set to `true` an user with the Admin role can grant the role Superuser to any
## LDAP authentication
At the moment LDAP users still have to be created manually in JATOS' _User manager_ (with the switch LDAP turned on). Only the authentication is done via LDAP.
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:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ In the beginning every study has only one batch, the 'Default' one, but more can

## 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).
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**

Expand All @@ -38,12 +38,12 @@ You can de-/activate a study link type by clicking on the switch in the left of

Personal type links can be either "Single" or "Multiple". You can find more details about them in the [Worker Types](Worker-Types.html) page, but the gist is that the links are meant to be handed to individual workers (hence _Personal_). Personal Single links can be used once, whereas Personal Multiple can be used many times.

After clicking the **Study Links** button you get a new window where you can create and manage the study links of this type.
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](/img/v39x/study_links_11.png)

1. This button creates one study link without a comment. This button is a shortcut to the "New Study Links" button.
1. Lets you create several study links and lets you add a comment to them. The comment is only a hint for you that you can use to distinguish your study links. You can create Personal type study links in bulk by changing the Amount value.
1. This button adds one study link without a comment. This button is a shortcut to the "New Study Links" button.
1. 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.
1. This is the study code. [You can hand this to your workers](Run-your-Study-with-Study-Links.html#study-code--study-entry-page).
1. This is your actual study link. Hand this to your workers. There are two links that can be toggled by a button: 1) [The 'Open Directly' link starts the study right away](Run-your-Study-with-Study-Links.html#start-directly-with-a-study-link). 2) [The 'Confirm First' lets your worker confirm first with a button press](Run-your-Study-with-Study-Links.html#study-link--study-entry-page-for-confirmation). Use the <span class="glyphicon glyphicon-duplicate"></span> button to copy the link to the clipboard or <span class="glyphicon glyphicon-qrcode"></span> to get the QR code.
1. 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).
Expand Down Expand Up @@ -71,7 +71,7 @@ There are two links that can be toggled by a button: 1) [The 'Open Directly' lin

![Study Links page screenshot](/img/v39x/study_links_6.png)

How to connect to MTurk and create study links is described in its own page: [Connect to Mechanical Turk](Connect-to-Mechanical-Turk.html).
How to connect to MTurk and add study links is described in its own page: [Connect to Mechanical Turk](Connect-to-Mechanical-Turk.html).


## Study Entry Page
Expand Down Expand Up @@ -121,7 +121,7 @@ The advantage of using the Study Entry page with the study codes is similar to a

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

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -73,11 +73,11 @@ If the `jatos.abortStudy` function is called (usually after the worker clicks a

### 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.
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 artifically throttle the network speed in [Firefox's](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) and [Chrome's](https://developers.google.com/web/tools/chrome-devtools/network#throttle) Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.
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](https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor) and [Chrome's](https://developers.google.com/web/tools/chrome-devtools/network#throttle) Developer Tools. Choose a slower connection, e.g. '3G', and try out your study again. This works on every JATOS, local or a remote.

### Personal/General Single links seem not to work when distributed via social networks

Expand Down
Loading

0 comments on commit 51ff813

Please sign in to comment.