Controlling Survey Quotas with Javascript

Learn how to access and control survey quota data with custom Javascript in Web Survey Creator.
Reference Guide
Survey quotas measure how many surveys are to be completed by survey respondents. If a certain quota for a type of respondent has already been met, the survey respondent can be "quota outed", which may send them to a terminate page and end the survey.

Sometimes you need to have your survey react in very specific ways to quotas so that different pathways can be taken based on how many quotas have been filled.

Scripting can be used to review survey quotas and then select choices or undertake other actions. Selecting choices might allow additional quotas to be calculated or Flow Control to operate based on current quota calculations.

The WSC scripting object offers a variety of useful scripting methods for dealing with quota management in Javascript:
  • wscScripting.getQuotaByCode(code)
  • wscScripting.getQuotaByIdentity(identity)
  • wscScripting.isQuotaFull(quota)
  • wscScripting.sortQuotasByLeastFilled(quotas)
  • wscScripting.sortQuotasByMostFilled(quotas)
The starting point for getting quota data in scripting is by using the getQuotaByCode() WSC scripting method. EG:

var oMyQuota = wscScripting.getQuotaByCode('PUT-QUOTA-CODE-HERE');

Sorting Quotas based by Least Filled Example

Let's look at a basic step-by-step example of allocating quotas based on a least filled principle using Javascript. The goal will be to assign respondents to one of four quota groups. In this example, male respondents will be allocated to a quota group 1 or 2 based on the least filled quota during their response. Female respondents will follow the same process for groups 3 and 4:
  • 1. Navigate to Design --> Content and add the survey questions. This example will require choice questions to determine the respondent gender and quota group allocation.
    Javascript Quota Questions
  • 2. Quotas will need to be created for the Groups question. Navigate to Design --> Survey Quotas. Use the Generate Quotas from Questions button to create some new quota limits.
    Javascript Quota Generation
  • 3. Before quota data can be accessed with Javascript - the quota data must be loaded. Add a new Javascript script to the same survey page as the Groups quota question. Set the script to the "Execute Javascript when Survey Quota Data has been Loaded" scripting event. No Javascript code needs to be added to this script, it will just need to exist on the page so that the survey quota data can be accessed.
    Javascript Load Quota Data
  • 4. Add another script to the survey page set to the "On Next/Submit" scripting event. The following script will identify which choice is selected at the Gender question, get and sort the quotas based on least filled and then select a group choice in the Groups question. Before the quotas are sorted in Javascript - the array of quotas is randomised to reduce bias.
///Get the survey questions
var oGender = wscScripting.getQuestionByDataPipingCode('GENDER');
var oGroups = wscScripting.getQuestionByDataPipingCode('GROUPS');

///Create an array to hold the survey quotas
var aQuotas = new Array();

///Identify which choice has been selected in the gender question
if (wscScripting.isChoiceSelectedByValue(oGender, 1)) {
///If Male is selected, push quota groups 1 and 2 into the quotas array
} else {
///If Female is selected, push quota groups 3 and 4 into the quotas array

///Randomise the array the quotas first

///Sort the quota array based on least filled quotas

///The least filled quota will be moved to the first position in the array
///Save the quota to a variable
var oQuota = aQuotas[0];

///Use the quota code to select it's matching group
if (oQuota.code == 'GROUP1') {
wscScripting.selectChoiceByValue(oGroups, 1);
else if (oQuota.code == 'GROUP2') {
wscScripting.selectChoiceByValue(oGroups, 2);
else if (oQuota.code == 'GROUP3') {
wscScripting.selectChoiceByValue(oGroups, 3);
else if (oQuota.code == 'GROUP4') {
wscScripting.selectChoiceByValue(oGroups, 4);

args.isValid = true;

Identifying if a Quota is already Full

There may be times where you don't want a particular quota to be selected if it is already full. In these circumstances the WSC scripting method isQuotaFull() can be used to determine if a quota is full and therefore take different pathways in your script.

A quick example of testing current quota capacity::

var myQuota = wscScripting.getQuotaByCode('QUOTACODE');
var isMyQuotaFull = wscScripting.isQuotaFull(myQuota);

If the tested quota is full, the method will return true and can therefore be used in scripting logic.