Registering your Qualtrics credentials
There are two ways to register your Qualtrics credentials (your API key and institution-specific root url) and other options in R. As in earlier versions of the qualtRics package, you can register your credentials at the start of each R session:
registerOptions(api_token="<YOUR-API-TOKEN>", root_url="<YOUR-ROOT-URL>")You can set some global options via the registerOptions() function:
- verbose: Logical. If TRUE, verbose messages will be printed to the R console. Defaults to TRUE.
- useLabels: Logical. TRUE to export survey responses as Choice Text or FALSE to export survey responses as values.
- convertStandardColumns: Logical. If TRUE, then the function will convert general data columns (first name, last name, lat, lon, ip address, startdate, enddate etc.) to their proper format. Defaults to TRUE.
- useLocalTime: Logical. Use local timezone to determine response date values? Defaults to FALSE.
- dateWarning: Logical. Once per session, qualtRics will emit a warning about date conversion for surveys. You can turn this warning off by changing the flag to FALSE. Defaults to TRUE.
You can change some of these options without having to pass the api_token or root_url parameters every time as long as you have registered the api token and root url previously:
registerOptions(verbose=FALSE, useLocalTime=TRUE)The second method involves placing a configuration file called .qualtRics.yml in your working directory.
Using a configuration file
qualtRics supports the use of a configuration file to store your Qualtrics credentials. Executing qualtRicsConfigFile() returns information that explains how you can do this:
Copy-paste the lines between the dashes into a new plain text file, replace the values for the
api_token and root_url if they are not yet filled out. and save it in your working directory
as '.qualtRics.yml'. Execute '?qualtRics::qualtRicsConfigFile' to view an explanation of the additional arguments.
Visit https://github.com/JasperHG90/qualtRics/blob/master/README.md#using-a-configuration-file
for more information.
--------------
api_token: <YOUR-API-TOKEN-HERE>
root_url: <YOUR-ROOT-URL-HERE>
verbose: TRUE
uselabels: TRUE
convertstandardcolumns: TRUE
uselocaltime: FALSE
dateWarning: TRUE
--------------You can also call this function while passing api_token and root_url values to the function, in which case <YOUR-API-TOKEN-HERE> and <YOUR-ROOT-URL-HERE> will be replaced by your credentials. After saving the file, you can register your credentials by calling registerOption() without passing any parameters.
When you load the qualtRics package, it will automatically look for a .qualtRics.yml file in the working directory, in which case you don’t need to call the registerOption() function to register your qualtRics credentials at the beginning of your session.
You can override your configuration file settings by calling registerOption() with the changes you want to make:
registerOptions(verbose=FALSE, useLabels=FALSE, root_url="myinstitution.qualtrics.com")Setting up a config file
Open an existing R project or start a new one. Then, open up an empty text file:
Execute qualtRicsConfigFile(api_token="<YOUR-API-TOKEN-HERE>", root_url="<YOUR-ROOT-URL-HERE>") and copy-paste the text between the dashes to the empty text file: