Introduction:
Python is a general purpose open-source programming language whose popularity is considered one of the fastest-growing in recent years. Qualtrics is one of the world’s leading survey platforms designed to simplify and accelerate the process of capturing human insights. Both Python and Qualtrics have allowed me to help A LOT in streamlining survey processes for clients. I thought I’d share my experiences with those who might also want to streamline their survey process.
The purpose of this tutorial is to demonstrate how Python can be used together with Qualtrics and Windows Task Scheduler to automate the full survey process, bypassing routine and boring steps of preparing a flat-file, uploading it into Qualtrics and scheduling it for distribution. No coding experience is necessary because we’ve already created a custom Python package that interacts with Qualtrics using its so-called Application Programming Interface (API). This tutorial was created in a Windows environment, but it should be possible to replicate in any operating system, though we don’t explore it here.
Requirements:
To follow along with this tutorial, please complete the following three steps:
1. Verify you have access to a Qualtrics account with API add-on, which is not including in as part of Qualtrics’ Research Suite. If you do not have the API add-on, please reach out to your Qualtrics Product manager to purchase it.
2. Install Python 3.6 or newer, which can be downloaded at https://www.python.org/downloads/
3. Install the PyCharm Community Edition IDE, which is available for free from JetBrains, per the instructions provided here: https://www.jetbrains.com/help/pycharm/requirements-installation-and-launching.html
The basic process for automating a Qualtrics survey workflow is as follows:
Finding Qualtrics API Tokens and Qualtrics Object IDs
1. Start by logging into Qualtrics as you normally do.
2. Create a new test survey project. You just need at least one question set up for the purpose of this tutorial.
3. Create an email message for this survey. You can do this in the top navigation bar by clicking on Library > Messages Library > [New Message]. Remember to name the email message something easy to remember and identify. Also, make sure the Message Type is set to “Invite Emails.”
4. Then, go to Account Settings in the user dropdown in the upper-right corner of the page.
5. Navigate to Qualtrics IDs in the menu across the top
6. Here you will find your API Token. If this is your first time, click [Generate Token].
Your API Token is a unique string that substitutes as your conventional login name and login password. It’s important to protect this token the same way you would your login and password since it grants privileged access to your Qualtrics account.
7. On this page you will also find Qualtrics Object IDs, including Survey IDs, Library IDs, panels IDs, messages IDs, and other library elements.
Almost every Qualtrics object you create on the web can be identified by an abbreviation followed by a unique ID number. For example, mailing lists begin with an ‘ML_’ followed by a long sequence of digits. This combination of two letters, an underscore, and digits is how we can interact with Qualtrics Objcts usingthe API.
8. Look for your Library ID. It should begin with ‘GR_’.
9. Look for the survey project you created and note down its Survey ID. It should begin with ‘SV_’.
10. Look for the survey message you created and note down its Message ID. You will find your Message ID under the “Invite Email” section of your Library. It should begin with ‘MS_’.
You will need each of these IDs when setting up your Python instance.
Setting up your Python Instance and Example Script
Installing the qualtrics-mailer package
We’ve created a package to help load a mailing list and distribute Qualtrics surveys using Python and the Qualtrics API. In this example, we will assume you already have Python 3.6 or newer and the PyCharm IDE installed.
1. Start your instance of PyCharm and create a new Pure Python Project. We recommend you create a virtual environment as well since it’s considered best practice to use a separate virtual Python environment for each project.
When creating a Python project in PyCharm, pick a directory to save the project under ‘Location’. In the example below, the project will be saved in the folder ‘qualtrics-mailer’ and the virtual environment (‘venv’) will be nested inside ‘qualtrics-mailer.’
2. Once initialized, you should see the following screen.
3. Next, we will import the qualtrics-mailer package. This package contains all the code you’ll need to upload a mailing list and distribute a survey, without needing to interact with the Qualtrics website. Start by going to File > Settings.
In the settings window, you want to select “Project: qualtrics-mailer” on the left tool bar and then click on ‘Project Interpreter’. In the menu on the right side, click on the green ‘plus’ sign. This will bring up a packages-search window where you will type ‘qualtrics-mailer’ and click ‘Install Package.’
At this point, you can close out of the windows to go back to the main PyCharm window. On the bottom right of the screen, it will tell you the status of the package installation, please wait for it to complete before proceeding:
Entering Qualtrics Attributes
With the qualtrics-mailer package installed, it’s time to enter Qualtrics account attributes and Object IDs. Begin by creating a new Python file and naming it “main.py”. You can also copy and paste the full code from https://github.com/KaiAnalytics/qualtrics_mailer/blob/master/example_usage.py.
Line by Line Walk-Through
1. Let’s begin by importing both system packages and objects from the qualtrics-mailer packages, which is called “qualtrics_mailer” in Python since Python object names can’t contain dashes:
from datetime import datetime
from pprint import pprintfrom qualtrics_mailer import (
QualtricsAccount,
QualtricsDistribution,
QualtricsMailingList
)2. Next, we input a Qualtics API token and Qualtrics Data Center before initializing a Qualtrics Account object. (Note: In the code below, replace the text in ‘single quotes’ with your own settings, and keep the single quotes!)
# set data center and API token
api_token = ‘[your account API token]’
data_center = ‘[your account data center name]’# initialize Qualtrics Account object
account = QualtricsAccount(api_token, data_center)To find your data center, look for the first part of your Qualtrics URL when you sign into the web interface. So, for example, my Qualtrics URL is “https://co1.qualtrics.com/ControlPanel/”, so in this case, I would replace the third line of code above with the following:
data_center = ‘co1’
3. Next, we input Qualtrics Object IDs before initializing a Qualtrics Mailing List object.
# set library id, mailing list, and category name
library_id = ‘[valid library id for your account]’
mailing_list_name = ‘[Example Usage List Name]’
category_name = ‘[Example Usage Category Name]’# initialize Qualtrics Mailing List object
mailing_list = QualtricsMailingList(
account,
library_id,
mailing_list_name,
category_name
)The library_id should be a string of characters that begins with ‘GR_’.
The mailing_list_name is anything you want to name your mailing list as. An ideal naming convention is to use a unique date and time stamp, replacing
mailing_list_name = ‘[Example Usage List Name]’
with the following (note that there are no single quotes since we’re replacing a literal string with a Python command):
mailing_list_name = datetime.now().strftime(‘%Y%m%d-%H%M%S’)
The category_name is the folder name for your mailing list. It will help you keep all the mailing lists for one survey grouped together in a single directory in Qualtrics.
4. Next, we load a mailing list, which will be imported into Qualtrics. The example file is available at https://github.com/KaiAnalytics/qualtrics_mailer/blob/master/example_mailing_list.csv and should be saved into the Project directory so the script can find it.
# import example contact list from test folder
with open(‘example_mailing_list.csv’) as fp:
mailing_list.import_contact_list_from_csv_file(fp)
# print mailing list’s contact list to confirm proper import
pprint(mailing_list.contact_list)Alternatively, if you want to save the file elsewhere, edit the line
with open(‘example_mailing_list.csv’) as fp:
with the directory where you saved your mailing list file:
with open(‘full/path/to/example_mailing_list.csv’) as fp:
Side note on querying a database In this tutorial, we use an example excel file, but there’s nothing stopping the user from building a mailing list by directly querying the database. To query a database directly, we recommend the SQLAlchemy package available from https://www.sqlalchemy.org/. At the end of the tutorial we’ll explore ideas to maximize survey automation at your institution.
5. Finally, we set up a distribution for a survey.
# set message id, survey id, and email settings
message_id = ‘[valid message id for your account]’
survey_id = ‘[valid survey id for your account]’
send_date = datetime.now().strftime(‘%Y-%m-%dT%H:%M:%SZ’)
from_name = ‘[Example Usage From Name]’
reply_email = ‘[Example.Usage@From.Name]’
subject = ‘[Example Usage Subject]’
distribution = QualtricsDistribution(
mailing_list,
message_id,
survey_id,
send_date,
from_name,
reply_email,
subject,
)
# print survey-distribution details to confirm proper creation
pprint(distribution.details)For message_id, enter the string of characters that begins with ‘MS_’.
For survey_id, enter the string of characters that begins with ‘SV_’.
The send date uses an ISO 8601 format, which defaults to the time the script is run. You will likely want to replace it with a custom time, such as
send_date = ‘2018–02–14T18:30:00–08:00’
The line above will send out the survey at 6:30 pm Pacific Standard Time (GMT-8:00) on February 14, 2018. You can read more about the ISO 8601 time format here: https://www.iso.org/iso-8601-date-and-time-format.html
The remaining three fields should be self-explanatory. In single quotes, include the sender name, sender email address, and subject of the survey email.
With that done, you can run the script by clicking Run in the top navigation bar of PyCharm:
If everything was entered correctly, the code will run, and you should be able to see the mailing list and survey distribution created when you log into Qualtrics.
WELL DONE! Now the final step is to set up Windows Task Scheduler to automatically run the qualtrics-mailer Python script.
Setting up Windows Task Scheduler to Automatically Run a Python Script
Windows Task Scheduler will allow you to run a Python script automatically at a set time, as follows:
1. First, find and open Windows Task Scheduler. If you are on a Windows 7 or higher, you should be able to just search “Task Scheduler” in the Start Menu. The program looks like this:
2. Create a new task by clicking on the top navigation bar: Action > Create Task
3. On the General page, make sure you have the highest privilege checked. Also, it would be good to name your task and give it a good description.
4. Under Trigger, set when and how often the task will run.
In our example, we arbitrarily set it to run at around 9 am on Mondays, Wednesdays, and Fridays.
5. Under actions, we set up the program, file, and file path that the task will run. In this case, we will run a) a Python interpreter; b) with the arguments in the main.py script; c)in the qualtrics-mailer project folder, as in the following example:
Pointing your Action to the right Python.exe It’s important to note that earlier in our example we recommended creating a virtual environment when setting up your Python qualtrics-mailer project. If you didn’t create a virtual environment, then use the global Python.exe program (e.g., C:\Users\USERNAME\AppData\Local\Programs\Python\Python36–32\python.exe) under Program/script. However, if you did create a virtual environment, then use the Python.exe program in the virtual environment directory (e.g., C:\Users\USERNAME\qualtrics-mailer\venv\bin\python.exe) under Program/script. If you don’t match the right Python.exe program, your task will not run correctly since it won’t be able to find the necessary packages to execute the script!
6. The last tab, Conditions, is worth looking at but not necessary for the purposes of the tutorial.
7. Depending on your security privilege, you may now save the task and …VOILA! You’ve successfully automated your Qualtrics survey project. If you want to test it, find the task you just created from the task list, right click and select “run”. If you refresh your task list again, you should see a status message such as, “The Operation Completed Successfully.”
Possible Use Cases Beyond This Tutorial
In our tutorial example, we used a CSV flat-file. This might be ideal if you want to routinely survey the same number of folks repeatedly over time. However, it is likely you might want to conduct a survey on a different set of populations over time, in which case you might want to directly query a database.
For a project, we created a qualtrics-mailer script to survey new customers in order to gauge their level of satisfaction. Without automation, the client would need to manually run a list of new customers, save their emails into a CSV file, upload the file into Qualtrics, and send out the survey every day. Instead, our qualtrics-mailer script performs this workflow for us every morning at 9:00 a.m. and schedules a new survey to go out at 6:30 pm everyday from Monday to Saturday, unless there are no new customers for a given day.
Based on my experience in higher-education, it’s possible to use the qualtrics-mailer script to automate course evaluations. This can be accomplished by automating queries to a student database at the end of each academic term and sending surveys to all students enrolled in each class. Schools could potentially save thousands of dollars a year on third-party course evaluation solutions.
The Qualtrics API is well developed and robust, so it’s not only possible to distribute surveys, but also to import survey results. This opens the possibilities of automating survey results directly into visualization tools, such as Microsoft Power BI or Tableau.
For more information about using Python, we recommend the official Python Software Foundation’s tutorial at https://docs.python.org/3/tutorial/. Another excellent resource is The Hitchhiker’s Guide to Python!, available at http://docs.python-guide.org/
A big thanks to my colleague Isaiah Lankham for collaborating on the qualtrics-mailer package. For those interested in Python, we co-host a podcast, Python Out Loud, about the Python programming language and the process of learning software development. You can follow us on Twitter @PythonOutLoud.
Comments