help for qualtrics v2.0 March 2020

Title

qualtrics -- List, download, and clean surveys from the Qualtrics API

Syntax

qualtrics set, [set_options] Set a password to use instead of the token and data center each call

qualtrics list, [list_options] List surveys associated with your account, filter results

qualtrics get, [get_options] Download survey, convert to .dta and clean

set_options Description

token(strings:string) Qualtrics API token

center(strings:string) Data center used for your Qualtrics account

password(strings:string) Password to encode and decode Qualtrics token and data center

user(strings:string) Specify a user to pair with password (optional)

list_options Description

match(strings:string) Return survey names matching a regular expression

active(strings:string) Return only active or inactive surveys surveys

modrange(MDY:MDY) Return only surveys last modified in a date range

createrange(MDY:MDY) Return only surveys created in a date range

token(strings:string) Required if not using a set password

center(strings:string) Required if not using a set password

password(strings:string) Required if not specifying token and center

user(strings:string) User paired with password (optional, if password not set with user)

get_options Description

id(strings:string) Qualtrics survey ID (can display with qualtrics list)

csv(strings:string) Folder to save CSV (file is named as it is in Qualtrics)

dta(strings:string) File name and folder path to save .dta

valuelabs Request file with value labels instead of numeric codes (not compatible with clean)

clean Apply variable and value labels, store item information in characteristics (not compatible with valuelabs)

relab Display label variable commands to make manual adjustments (must use clean)

revallab Display label values commands to make manual adjustments (must use clean)

preserve Restore current dataset (rather than loading downloaded file)

token(strings:string) Required if not using a set password

center(strings:string) Required if not using a set password

password(strings:string) Required if not specifying token and center

user(strings:string) User paired with password (optional, if password not set with user)

Description

qualtrics provides tools to list, download, convert, and clean Qualtrics surveys using the Qualtrics API.
qualtrics list displays surveys associated with the users account including the survey id (required to download), the creation time, modified time, and whether the survey is active.
qualtrics get downloads the .csv version of the survey, and then optionally converts it to .dta, and applies variable and value labels.
It also stores other item information, including question stems, in variable characteristics.
qualtrics set allows users to set a password (and optional user name) which stores the Qualtrics data center and encrypts and stores the Qualtrics token in a text file in the user's personal .ado path.
Users may either specify their Qualtrics token and data center each time qualtrics list or qualtrics get is called or use qualtrics set and then provide the password for each call.
qualtrics requires a cURL installation that can be called by Stata with the shell(!) command.

qualtrics set

qualtrics set is used to set up your token and data center so you do not need to specify them each time you run a qualtrics command.
It is not required that you set qualtrics, you may instead specify the token and center each time, but is is not reccomended, especially if sharing syntax with outside organizations who should not have access to your token.

token(strings:string) is used to enter your qualtrics token so that it can be encrypted and saved to a text file in your personal ado path to be read in on subsequent qualtrics list and qualtrics get calls.
To find your API token, log in to your Qualtrics account, and navigate to account setting by clicking on the icon in the upper right corner.
Click on Qualtrics IDs on the top bar, your token is listed (or can be generated) under the API section.
Important Note: Your token can be used to edit and delete surveys and survey responses.
A bad actor could do considerable harm with it, so be sure not to share or expose it, and it is wise to encode it using qualtrics set.

center(strings:string) is used to enter your qualtrics data center so that it can be saved to a text file in your personal .ado path to be read in on subsequent qualtrics list and qualtrics get calls.
To find your data center, log in to your Qualtrics account, and examine the url.
The url will look something like "yourorgname.datacenter.qualtrics.com."
It will be something like co1, az1, or ca1.

password(strings:string) is a password you select. The password is used to encrypt your qualtrics token, and is required to decrypt it. It can include most any ASCII text except the left tick (`) used to define locals.
Once you set qualtrics once, you should not need to do so again, unless you delete the file containing the information. If you forget your password, you can always qualtrics set again (and enter your token and data center again).

user(strings:string) is an optional user name you can pair with a password. You might want to do so if you have more than one Qualtrics account and need to store your token and data center separately.
You may also want to do so if you have multiple users who share the same .ado path and would like to use different passwords.
If you qualtrics set with the user option you must continue to specify the user in your qualtrics list and qualtrics get calls.

qualtrics list

qualtrics list lists the surveys associated with the API token provided, and can filter the list in several ways.

match(strings:string) is used to limit the surveys qualtrics list returns.
qualtrics list will only return surveys whose survey name matches the regular expression string entered in this option.
Note that you will have to use a \ before ()[].+*?-|&^$ if your survey name includes a literal regular expression notation.
For example, to return surveys that match "Fall 2020 Survey (version 1)", you would type something like m(2020 Survey \(version 1\)).

active(strings:string) is used to return either active or inactive surveys as defined by Qualtrics.
Entering "true" will return active surveys only, and "false" will return inactive surveys only.

modrange(start MDY:end MDY) is used to return surveys which were last modified in a date range. The required format is modr(month date year:month date year) with the start date first and the end date second.
The start and dates must be separated by a colon(:) and be in MDY format.
Any version including four-digit years which the date(XXX,"MDY") can interpret is acceptable.

createrange(start MDY:end MDY) is used to return surveys which were created in a date range. The required format is creater(month date year:month date year) with the start date first and the end date second.
The start and dates must be separated by a colon(:) and be in MDY format.
Any version including four-digit years which the date(XXX,"MDY") can interpret is acceptable.

token(strings:string) is used to enter your qualtrics token if you opt not to use qualtrics set.
See the documentation in set options for instructions on finding your token.
Important Note: Your token can be used to edit and delete surveys and survey responses.
A bad actor could do considerable harm with it, so be sure not to share or expose it, and it is wise to encode it using qualtrics set.

center(strings:string) is used to enter your qualtrics data center if you opt not to use qualtrics set.
See the documentation in set options for instructions on finding your data center.

password(strings:string) is the password you used in a previous qualtrics set command.

user(strings:string) is an optional user name you may have paired with a password in a previous qualtrics set command.

qualtrics get

qualtrics get downloads, converts and cleans designated survey.

id(strings:string) is used to specify the Qualtrics survey ID to be downloaded.
IDs can be found by using a qualtrics list command.

csv(strings:string) is used to select the folder to save the .csv survey downloaded.
Do not provide a file name, only a folder path.
The file is named by Qualtrics.
This option is required.

dta(strings:string) is used to specify the location and name to use saving a converted .dta file.
Unlike the csv option, a file name should be included.
This option must be included if selecting the clean, relab, or revallab options.

valuelabs is used to request value labels, rather than numeric codes.
The resulting .csv will have strings with the response option text.
This option may not be combined with the clean option.

clean is used to download the survey meta-data and apply variable labels and value labels to the variables.
It will also store the question stems and labels in the variable characteristics.
Note: Qualtrics has numerous question formats and this information is often stored differently.
For this reason the clean function may not catch value labels for all types of questions, or may capture labels which are not as informative as one might like.

relab is used display code which can be pasted into a .do file to make manual adjustments to variable labels.
This can be useful if variable labels are truncated or otherwise need to be edited.
This information is also stored in variable characteristics, which can also be used to adjust labels
The clean option must be selected if using this option.

revallab is used display code which can be pasted into a .do file to make manual adjustments to value labels.
This can be useful if value labels are truncated or otherwise need to be edited.
The clean option must be selected if using this option.

preserve is used to restore the dataset in memory when qualtrics get is run.
The default is to load the downloaded dataset.

token(strings:string) is used to enter your qualtrics token if you opt not to use qualtrics set.
See the documentation in set options for instructions on finding your token.
Important Note: Your token can be used to edit and delete surveys and survey responses.
A bad actor could do considerable harm with it, so be sure not to share or expose it, and it is wise to encode it using qualtrics set.

center(strings:string) is used to enter your qualtrics data center if you opt not to use qualtrics set.
See the documentation in set options for instructions on finding your data center.

password(strings:string) is the password you used in a previous qualtrics set command.

user(strings:string) is an optional user name you may have paired with a password in a previous qualtrics set command.

qualtrics set examples

An example not specifying a user.
qualtrics set, t(`"QualtricsAPITokenHere"') c(`"co1"') password(ApassW0rd)

Specifying a user as well.
qualtrics set, t(`"QualtricsAPITokenHere"') c(`"az1"') password(ApassW0rd) u(danial)

qualtrics list examples

List all surveys using the password.
qualtrics list, password(ApassW0rd)

List all surveys using the password and user.
qualtrics list, p(ApassW0rd) u(danial)

List all surveys using the token and data center instead of the password.
qualtrics list, t(`"QualtricsAPITokenHere"') c(`"co1"')

List surveys whose name includes "Fall 2020".
qualtrics list, password(ApassW0rd) m(Fall 2020)

List surveys whose name includes "Fall 2020", "Fall 2019" or "Fall 2018".
qualtrics list, password(ApassW0rd) m(Fall 20[1-2][890])

List surveys whose name includes "Fall 2020" and last modified between April 20th 2020 and December 15th 2020.
qualtrics list, password(ApassW0rd) m(Fall 2020) modr(Apr 20 2020:Dec 15 2020)

List active surveys created between April 20th 2020 and December 15th 2020.
qualtrics list, password(ApassW0rd) a(true) creater(4/20/2020:12/15/2020)

qualtrics get examples

Get a csv file of a survey using the password
qualtrics get, id(`"SV_XYXYXYXYX"') csv(`"C:/Users/dhoepfner/Desktop/"') password(ApassW0rd)

Get a survey and convert to stata using the token and data center
qualtrics get, id(`"SV_XYXYXYXYX"') t(`"QualtricsAPITokenHere"') c(`"az1"') ///
csv(`"C:/Users/dhoepfner/Desktop/"') dta(`"C:\Users\dhoepfner\Desktop\testdata.dta"')

Get a survey, convert and clean it, output text to modify variable and value labels
qualtrics get, id(`"SV_XYXYXYXYX"') password(ApassW0rd) csv(`"C:/Users/dhoepfner/Desktop/"') ///
dta(`"C:\Users\dhoepfner\Desktop\testdata.dta"') clean relab reval

Author

Danial Hoepfner, Gibson Consulting Group Inc., dhoepfner@gibsonconsult.com or danial.hoepfner@gmail.com