Difference between revisions of "Qualtrics linking"

From Solowiki
Jump to navigation Jump to search
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Studies hosted on JATOS, Gorilla or Pavlovia can be integrated with Qualtrics in a way which allows information exchange in both directions: from the studies to Qualtrics, and vice versa. Both methods use [Query Strings https://en.wikipedia.org/wiki/Query_string] and typically involve redirecting participants to an online study after they have completed a Qualtrics survey; and/or redirecting participants to a Qualtrics survey after they have completed an online study.
+
Studies hosted on JATOS, Gorilla or Pavlovia can be integrated with Qualtrics in a way which allows information exchange in both directions: from the studies to Qualtrics, and vice versa. Both methods use [https://en.wikipedia.org/wiki/Query_string Query Strings] and typically involve redirecting participants to an online study after they have completed a Qualtrics survey; and/or redirecting participants to a Qualtrics survey after they have completed an online study.
  
 
== Linking to Qualtrics ==
 
== Linking to Qualtrics ==
Under construction
 
  
Add variables to
+
=== OSWeb/JATOS Implementation ===
* Survey Flow
 
* Add Embedded Data
 
* Add a new field -> name of variable
 
  
 +
Follow the steps below to link from an OSWeb task to Qualtrics.
  
=== OSWeb/JATOS Implementation ===
+
We also provided the following demo task in OpenSesame:
Under construction.
+
 
 +
Download task: [https://solowiki.services.universiteitleiden.nl/images/6/61/JatosToQualtrics.zip JatosToQualtrics.osexp] 
 +
 
 +
Run online: [https://jatos.services.universiteitleiden.nl/publix/131/start?batchId=166&generalMultiple Demo - Linking to Qualtrics]
  
 
==== Step 1: OpenSesame ====
 
==== Step 1: OpenSesame ====
Assuming you already have a survey in Qualtrics, edit it and go to ‘Distributions’ and click ‘Get single reusable link’.
 
  
In OpenSesame, add a inline_javascript object:
+
In OpenSesame, add an inline_javascript object (Figure 1) to the end of your experiment. If you don’t have the OSWeb section in the OpenSesame toolbar, please upgrade your OpenSesame to the latest version.
  
todo: image
+
[[File:Osweb extension2.png|thumb|right|Figure 1: The inline_javascript object.]]
Figure 1: The inline_javascript object. If you don’t have the OSWeb section in the OpenSesame toolbar, please upgrade your OpenSesame to the latest version.
 
  
Then, in the new object, copy the Qualtrics link and store it in a JavaScript variable:
+
Assuming you already have a survey in Qualtrics, edit it and go to ‘Distributions’ and click ‘Get single reusable link’.
<syntaxhighlight lang="javascript" line='line'>
+
In the inline_javascript object, paste the Qualtrics link and store it in a JavaScript variable:
 +
<syntaxhighlight lang="javascript">
 +
// example
 
var surveyUrl = 'https://leidenuniv.eu.qualtrics.com/jfe/form/SV_1SrURH8xI3jHbYV';
 
var surveyUrl = 'https://leidenuniv.eu.qualtrics.com/jfe/form/SV_1SrURH8xI3jHbYV';
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Now add the variables you want to send to the link:
+
If you also want to send some variables from OpenSesame to Qualtrics you can add these to the link:
  
<syntaxhighlight lang="javascript" line='line'>
+
<syntaxhighlight lang="javascript">
vars.subjectNr = 1; vars.favoriteColor = 'blue'; surveyUrl += '?favoriteColor=' + vars.favoriteColor; // first argument starts with '?'  
+
// example: sending variables to Qualtrics in Url
 +
vars.favoriteColor = 'blue';  
 +
surveyUrl += '?favoriteColor=' + vars.favoriteColor; // first argument starts with '?'  
 +
vars.subjectNr = 1;
 
surveyUrl += '&subjectNr=' + vars.subjectNr; // next arguments start with '&'
 
surveyUrl += '&subjectNr=' + vars.subjectNr; // next arguments start with '&'
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 35: Line 38:
 
''Note:'' It is also possible to send JATOS identifiers (e.g. studyId, workerId, batchId) to Qualtrics, see the example task for a demonstration.
 
''Note:'' It is also possible to send JATOS identifiers (e.g. studyId, workerId, batchId) to Qualtrics, see the example task for a demonstration.
  
Now instruct OpenSesame to open the link:
+
Now instruct OSWeb to exit and redirect to Qualtrics:
  
<syntaxhighlight lang="javascript" line='line'>
+
<syntaxhighlight lang="javascript">
window.open(surveyUrl);
+
try {
 +
jatos.endStudyAndRedirect(surveyUrl);
 +
} catch {
 +
// for testing without Jatos ('Run in browser')
 +
window.open(surveyUrl);  
 +
}
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 64: Line 72:
 
# Click options to specify the variable type (e.g. Number for subjectNr and Text for favoriteColor). Also see the image below.
 
# Click options to specify the variable type (e.g. Number for subjectNr and Text for favoriteColor). Also see the image below.
  
todo: image
+
[[File:Embedded data.png|thumb|center|Figure 2: Configuring embedded data in Qualtrics.]]
Figure 2: Configuring embedded data in Qualtrics.
+
 
  
 
''Now how can you use this information in your survey?''
 
''Now how can you use this information in your survey?''
  
Information from embedded data can be used in survey questions. To make it easy to use this data in this way, Qualtrics has the ‘Piped Text’ feature. More information about Piped Text is explained in the [https://www.qualtrics.com/support/survey-platform/survey-module/editing-questions/piped-text/piped-text-overview/ documentation].
+
Information from embedded data can be used in survey questions. To make it easy to use this data in this way, Qualtrics has the ‘Piped Text’ feature. More information about Piped Text is explained in the [https://www.qualtrics.com/support/survey-platform/survey-module/editing-questions/piped-text/piped-text-overview/ Qualtrics documentation].
  
todo: image
+
[[File:Piped_text.png|thumb|center|Figure 3: Example of using the piped text corresponding to the information we obtained from the OpenSesame demo task.]]
Figure 3: Example of using the piped text corresponding to the information we obtained from the OpenSesame demo task.
 
  
 
==== Step 4: Testing ====
 
==== Step 4: Testing ====
Line 79: Line 86:
  
 
== Linking from Qualtrics ==
 
== Linking from Qualtrics ==
Under construction.
 
  
 
=== OSWeb/JATOS Implementation ===
 
=== OSWeb/JATOS Implementation ===
Under construction.
+
 
 +
Follow the steps below to redirect from a Qualtrics Survey (after completion) to an OSWeb experiment on JATOS and (optionally) to send information from the survey to the experiment.
 +
 
 +
We also provided a demo OSWeb experiment that receives survey answers from Qualtrics:
 +
 +
Download task: [https://solowiki.services.universiteitleiden.nl/images/e/e4/QualtricsToJatos.zip QualtricsToJatos.osexp]
 +
 
 +
Run online: [https://leidenuniv.eu.qualtrics.com/jfe/form/SV_1SrURH8xI3jHbYV Demo - Linking from Qualtrics]
 +
 
 +
=== Step 1: OpenSesame ===
 +
 
 +
Suppose your Qualtrics Survey has two Questions:
 +
 
 +
1) What is your favorite food?
 +
2) What is your favorite animal?
 +
 
 +
To receive this information, you also have to make two JavaScript variables in OpenSesame, e.g. ‘favoriteFood’ and ‘favoriteAnimal’, and obtain their values.
 +
 
 +
 
 +
<syntaxhighlight lang="javascript">
 +
 
 +
// obtain information from JATOS Url
 +
var favoriteFood = jatos.urlQueryParameters.favoriteFood;
 +
// Set the variable value to 'unknown' if the Url does not contain a value for this variable
 +
vars.favoriteFood = favoriteFood ? favoriteFood : "unknown";
 +
var favoriteAnimal = jatos.urlQueryParameters.favoriteAnimal;
 +
vars.favoriteAnimal = favoriteAnimal ? favoriteAnimal : "unknown";
 +
 
 +
</syntaxhighlight>
 +
 
 +
Note: You can now show these variables in your experiment (e.g. on a Feedback item) or log them in the experiment log using the Logger item. See the demo experiment for a demonstration with both the Feedback display and the variable logging.
 +
 
 +
To save your experiment go to Tools -> OSWeb -> Experiment as JATOS study
 +
 
 +
=== Step 2: JATOS ===
 +
 
 +
# Log in to your JATOS server.
 +
# Click ‘Import Study’ and select your OpenSesame ZIP file.
 +
# Go the Study in JATOS and then to ‘Workers & Batch Manager’
 +
# Assuming you want a general (non-personal) re-usable link:
 +
## Select ‘General Multiple’ and click ‘Next’.
 +
## Copy the link to and empty NotePad document.
 +
 
 +
=== Step 3: Qualtrics ===
 +
 
 +
Now the final but also most essential step, correctly redirecting the participant from your survey to your JATOS study. Qualtrics has the option to redirect participants to custom webpages.
 +
 
 +
When editing your survey, you can find this option under ‘Survey Options’. In the ‘Survey Options’ dialog, in the section ‘Termination Options’, toggle ‘Redirect to a full URL, ex. "https://www.qualtrics.com"’. This is where you specify the link to the JATOS task AND the information you want to send to JATOS.
 +
 
 +
==== Redirect link construction: ====
 +
 
 +
Open your NotePad document with the JATOS link, e.g.:
 +
<syntaxhighlight lang="javascript">
 +
https://cortex.jatos.org/publix/68/start?batchId=68&generalMultiple
 +
</syntaxhighlight>
 +
 
 +
And add a line below similar to the following for each variable (as you defined in step 1):
 +
<syntaxhighlight lang="javascript">
 +
 
 +
&amp;favoriteFood=${q://QID6/ChoiceGroup/SelectedChoices}
 +
</syntaxhighlight>
 +
 
 +
In this example 'favoriteFood' is the name of the variable and '${q://QID6/ChoiceGroup/SelectedChoices}' is the piped text segment that corresponds to the selected answer to Question 6 (QID6). You can look up the Question ID in the Survey.
 +
 
 +
Finally, combine all lines into one long link, e.g.:
 +
 
 +
<syntaxhighlight lang="javascript">
 +
https://cortex.jatos.org/publix/68/start?batchId=68&generalMultiple&amp;favoriteFood=${q://QID6/ChoiceGroup/SelectedChoices}&amp;favoriteAnimal=${q://QID8/ChoiceGroup/SelectedChoices}
 +
</syntaxhighlight>
 +
 
 +
Copy and paste this link to the ‘Redirect URL’ box in the Survey Options dialog of your survey.
 +
 
 +
=== Step 4: Testing ===
 +
 
 +
# Open your survey and submit your answers.
 +
# Check the automatic redirection to the OSWeb task and complete the task
 +
# Check the exchange of variables (e.g. by checking the log file in the JATOS Results)

Latest revision as of 10:45, 21 September 2020

Studies hosted on JATOS, Gorilla or Pavlovia can be integrated with Qualtrics in a way which allows information exchange in both directions: from the studies to Qualtrics, and vice versa. Both methods use Query Strings and typically involve redirecting participants to an online study after they have completed a Qualtrics survey; and/or redirecting participants to a Qualtrics survey after they have completed an online study.

Linking to Qualtrics

OSWeb/JATOS Implementation

Follow the steps below to link from an OSWeb task to Qualtrics.

We also provided the following demo task in OpenSesame:

Download task: JatosToQualtrics.osexp

Run online: Demo - Linking to Qualtrics

Step 1: OpenSesame

In OpenSesame, add an inline_javascript object (Figure 1) to the end of your experiment. If you don’t have the OSWeb section in the OpenSesame toolbar, please upgrade your OpenSesame to the latest version.

Figure 1: The inline_javascript object.

Assuming you already have a survey in Qualtrics, edit it and go to ‘Distributions’ and click ‘Get single reusable link’. In the inline_javascript object, paste the Qualtrics link and store it in a JavaScript variable:

// example
var surveyUrl = 'https://leidenuniv.eu.qualtrics.com/jfe/form/SV_1SrURH8xI3jHbYV';

If you also want to send some variables from OpenSesame to Qualtrics you can add these to the link:

// example: sending variables to Qualtrics in Url
vars.favoriteColor = 'blue'; 
surveyUrl += '?favoriteColor=' + vars.favoriteColor; // first argument starts with '?' 
vars.subjectNr = 1; 
surveyUrl += '&subjectNr=' + vars.subjectNr; // next arguments start with '&'

Note: It is also possible to send JATOS identifiers (e.g. studyId, workerId, batchId) to Qualtrics, see the example task for a demonstration.

Now instruct OSWeb to exit and redirect to Qualtrics:

try {
	jatos.endStudyAndRedirect(surveyUrl);	
} catch {
	// for testing without Jatos ('Run in browser') 
	window.open(surveyUrl); 
}

To save your experiment. Go to Tools -> OSWeb -> Export experiment as JATOS study

Step 2: JATOS

  1. Log in to JATOS.
  2. Go to Import Study.
  3. Import your experiment ZIP file (e.g. MyExperiment.osexp.zip).
  4. Go to your Study and then to ‘Worker & Batch Manager’ (green button).
  5. Assuming you want a unique link for each participant that is usable only once:
    1. ‘Get Worker Links’ -> Select ‘Personal Single’ -> ‘Next’ -> Specify the amount of links needed -> Next
    2. Save these links somewhere to give to your participants and for testing.

Note: You can also make multiple batches and you can use other types of workers (e.g. anonymous users, multiple runs per user, and so on.)

Step 3: Qualtrics

The final step in this process in receiving the data in Qualtrics. Data obtained from URLs is called ‘Embedded Data’ in Qualtrics. First you have to specify which information is in the URL:

  1. Edit your Survey
  2. Go to Survey Flow
  3. Add the names of the variables you send in the Url (e.g. subjectNr and favoriteColor in the example above). These names are case sensitive.
  4. Click options to specify the variable type (e.g. Number for subjectNr and Text for favoriteColor). Also see the image below.
Figure 2: Configuring embedded data in Qualtrics.


Now how can you use this information in your survey?

Information from embedded data can be used in survey questions. To make it easy to use this data in this way, Qualtrics has the ‘Piped Text’ feature. More information about Piped Text is explained in the Qualtrics documentation.

Figure 3: Example of using the piped text corresponding to the information we obtained from the OpenSesame demo task.

Step 4: Testing

Open one of the JATOS Worker Links and check the experiment, the redirection to Qualtrics, and the information exchange.

Linking from Qualtrics

OSWeb/JATOS Implementation

Follow the steps below to redirect from a Qualtrics Survey (after completion) to an OSWeb experiment on JATOS and (optionally) to send information from the survey to the experiment.

We also provided a demo OSWeb experiment that receives survey answers from Qualtrics:

Download task: QualtricsToJatos.osexp

Run online: Demo - Linking from Qualtrics

Step 1: OpenSesame

Suppose your Qualtrics Survey has two Questions:

1) What is your favorite food? 2) What is your favorite animal?

To receive this information, you also have to make two JavaScript variables in OpenSesame, e.g. ‘favoriteFood’ and ‘favoriteAnimal’, and obtain their values.


// obtain information from JATOS Url 
var favoriteFood = jatos.urlQueryParameters.favoriteFood; 
// Set the variable value to 'unknown' if the Url does not contain a value for this variable 
vars.favoriteFood = favoriteFood ? favoriteFood : "unknown"; 
var favoriteAnimal = jatos.urlQueryParameters.favoriteAnimal; 
vars.favoriteAnimal = favoriteAnimal ? favoriteAnimal : "unknown";

Note: You can now show these variables in your experiment (e.g. on a Feedback item) or log them in the experiment log using the Logger item. See the demo experiment for a demonstration with both the Feedback display and the variable logging.

To save your experiment go to Tools -> OSWeb -> Experiment as JATOS study

Step 2: JATOS

  1. Log in to your JATOS server.
  2. Click ‘Import Study’ and select your OpenSesame ZIP file.
  3. Go the Study in JATOS and then to ‘Workers & Batch Manager’
  4. Assuming you want a general (non-personal) re-usable link:
    1. Select ‘General Multiple’ and click ‘Next’.
    2. Copy the link to and empty NotePad document.

Step 3: Qualtrics

Now the final but also most essential step, correctly redirecting the participant from your survey to your JATOS study. Qualtrics has the option to redirect participants to custom webpages.

When editing your survey, you can find this option under ‘Survey Options’. In the ‘Survey Options’ dialog, in the section ‘Termination Options’, toggle ‘Redirect to a full URL, ex. "https://www.qualtrics.com"’. This is where you specify the link to the JATOS task AND the information you want to send to JATOS.

Redirect link construction:

Open your NotePad document with the JATOS link, e.g.:

https://cortex.jatos.org/publix/68/start?batchId=68&generalMultiple

And add a line below similar to the following for each variable (as you defined in step 1):

&amp;favoriteFood=${q://QID6/ChoiceGroup/SelectedChoices}

In this example 'favoriteFood' is the name of the variable and '${q://QID6/ChoiceGroup/SelectedChoices}' is the piped text segment that corresponds to the selected answer to Question 6 (QID6). You can look up the Question ID in the Survey.

Finally, combine all lines into one long link, e.g.:

https://cortex.jatos.org/publix/68/start?batchId=68&generalMultiple&amp;favoriteFood=${q://QID6/ChoiceGroup/SelectedChoices}&amp;favoriteAnimal=${q://QID8/ChoiceGroup/SelectedChoices}

Copy and paste this link to the ‘Redirect URL’ box in the Survey Options dialog of your survey.

Step 4: Testing

  1. Open your survey and submit your answers.
  2. Check the automatic redirection to the OSWeb task and complete the task
  3. Check the exchange of variables (e.g. by checking the log file in the JATOS Results)