Managing Master Quota Studies

The use of a master quota file allows multiple studies to share and update quotas in real-time to help prevent overages.   Two or more different sample files with different dialing rules can share a quota file.  This is ideal for Business vs Consumer studies or Landline vs Cellphone dialing studies for example.

NOTE: See the Master Quota Webinar for more information.

Best Practices

  • You will have one Master Study + X number of Worker studies
    • You can have as many worker studies as you need, although most applications have two
  • Use a standard naming convention for the Master and the Worker studies to differentiate each worker study from the Master and so they sort together on the studies list.  For Example:
    • Bank_Master
    • Bank_Landline
    • Bank_Cellphone
  • Workers studies can be identical except for the study name
  • Best practice might include extra checking in the cell phone study to make sure it NEVER runs on a dialer.
    • If you have a “good” naming convention you probably can add code to the shell to determine from the study name that it is the cell study so you don’t need different code.
  • The Master study holds quotas across all worker studies
    • Setup the targets in the Master study
  • There should be one question in the master study which can be as simple as a Display or GOTO type question
  • Survox Console Only: A fone file needs to be built with at least one record in it for the Master study
  • The Worker studies update the master quota file
    • While each worker study can update their own quota files we do not recommend this because the quotas are harder to manage
  • MASTERQUOTA=<masterstudy> must be in each worker’s study header (REQUIRED)
    • This option links the worker studies with the master study
    • The <master>.quo file must be in the worker study directories to compile
  • We recommend using NEXTCASEID in the study header
    • This will avoid duplicates when combining the TR files
    • TR files can be combined at any point during the duration of the study to run reports and output files
  • We recommend using ALLOW_UNSET_QUOTAS in the study header for Master Quota studies ONLY
    • This allows quotas to be set up but not incremented within the spec
  • Each worker study will have separate sample files
  • Each worker study can have different phone parameters and dialing rules.  For example:
    • Dialing vs Manual Dialing
    • Daytime vs Nighttime Dialing

NOTE: If you are using a quota name in the fone file for the worker studies, you can use the command USE_MASTER_QUOTA=yes in the fone header to have all of the necessary quota commands refer to the master quota file study.

Master QPX Example

The Master study should hold all of the target quotas.  The quotas can be Triple-Quotas, Set Quotas, or Numbered Quotas.

Here is an example of a master quota study that has landline and cellphone quotas with gender quotas in both worker studies.

[MASTER,TQ,ALLOW_UNSET_QUOTAS]

{!TARGET COMPLETES=200 }

{!TARGET LANDLINE=100 }
{!TARGET LAND1=25 }
{!TARGET LAND2=25 }
{!TARGET LAND3=25 }
{!TARGET LAND4=25 }

{!TARGET CELLPHONE=100 }
{!TARGET CELL1=25 }
{!TARGET CELL2=25 }
{!TARGET CELL3=25 }
{!TARGET CELL4=25 }

{!TARGET MALES=100 }
{!TARGET FEMALES=100 }

{ Q1: !GOTO }

Update Quotas

To update Master quotas, the following syntax is used.  Master_Regular updates regular master quotas while Master_Numbered updated numbered master quotas.  These quota statements are used in each of the worker studies to update the master quota file.  The quotas can be based on system information, sample information, or question-driven, just like all other non-master quota types.

The syntax is:

!Quota,Master_Regular,<quota name>,<inc>,<now>
!Quota,Master_Regular,[<label name>],<inc>,<now>
!Quota,Master_Numbered,<quota number>,<inc>,<now>
!Quota,Master_Numbered,[<label name>],<inc>,<now>

Example:

[LANDLINE,TQ,ALLOW_UNSET_QUOTAS,MASTERQUOTA=MASTER,NEXTCASEID=10001 ]

In the above example, the study header is using the MASTERQUOTA=, NEXTCASEID, and ALLOW_UNSET_QUOTAS options.

{!QUOTA,MASTER_REGULAR,COMPLETES,1 }

{!IF Q1(01-04)
!QUOTA,MASTER_REGULAR,LANDLINE,1 }

>REPEAT $A=01,02,03,04; $B=1,2,3,4

{!IF Q1($A)
!QUOTA,MASTER_REGULAR,LAND$B,1 }
>ENDREPEAT

{!IF GENDER(01)
!QUOTA,MASTER_REGULAR,MALES,1 }

{!IF GENDER(02)
!QUOTA,MASTER_REGULAR,FEMALES,1 }

This is an example of how the master quotas would be updated from a worker study, in this case the LANDLINE worker study.  This will increment the number of completes, landline quotas, and gender quotas within the master quota study.

quotascreen

 

Check the Master Quota Values

You can check the quotas from the Master study by using the XF functions (Extended Functions) below. The use of these functions will returns the value at the beginning of the interview of the named master quota and are normally used in an EXPRESSION type question.

This is also useful if you are using markets in each of the worker studies.  You can get the value of the quota, check it against the target and if the quota is full, shutdown that market.

The syntax is:

XF(Master_Quota(<quotaname>))
XF(Master_Quota([<label name>]))
XF(Master_Numbered_Quota(<quota number>))
XF(Master_Numbered_Quota([<label name]))

Example:

{ OVERALL_FEMALE:
!EXPRESSION,,XF(MASTER_QUOTA,FEMALES) }

{ XFEMALES:
The total number of FEMALES IS \:OVERALL_FEMALES
!DISPLAY }

The above example will return the value of the master quota called FEMALES and display the value in the XFEMALES display question.

Cellphone Dialing

Best Practice is to put code in place in the Cell phone study to guarantee that it is not running on a dialer.  If you use a standard naming convention  like always ending the study name with the string “cell”, you can then put the name of the study into the data using a !SPECIAL,STUDY_INFO command and parse it to know whether or not it is a cell phone study.  You can use the following two commands to immediately exit.

{!System,Set_For_Interview_End,Quit }
{!Special,Abort }

Methods for Managing Master Quotas

There are two methods in setting up Master Quotas.  If you are a Non-Survox Console user, they can be set up via command line and if you do use the Survox Console, they can be set up via the Console.  Both methods are described below.

Command Line Method

  1. Create one <study> directory that will hold all portions of the study (Master + X number of Workers)
  2. Copy the Master spec and sample files to the <study> directory
  3. Copy each Worker spec and sample files to the <study> directory
  4. Compile the Master QPX first
  5. Compile each of the Worker QPX files after the Master QPX has been compiled
    1. Best Practice to ensure the quota files for all the studies are in sync, compile the Master first, then all the Workers, and then the Master one last time.
    2. The <master.quo> file must be in the worker study directories to compile the worker QPX files
  6. Build each of the Worker fone files
    1. Modify the phone parameters as necessary
    2. The Master study does not require a fone file when building studies via command line.
  7. If webCATI: Run WCATUTIL on each of the Worker studies to create their Theme
  8. Deploy the Master files live using Loadstudy
  9. Deploy the Worker files live using Loadstudy
  10. Configure the dialing rules for each of the worker projects in the Dialer Configuration file
    1. Dialing rules may be different depending on the type of sample
    2. NOTE: If dialing manually on a cell phone study, you should NOT be using the dialer at all.
  11. Check the quotas using either QUOTAMOD or display a QSS screen in a Supervisor session
    1. If only master quotas are used, all quota checking can be done in the Master study only
    2. If Non-Master quotas are also used within each of the workers, those quotas will need to be checked in each of the worker studies

Survox Console Method

  1. Via the Survox Console
    1. Create a project for all portions of the study (Master + X number of Workers)
      1. The Master holds the quota information
    2. Upload the Master spec and sample files under Project Setup
      1. Make sure you are uploading to the Master Project
      2. Build a fone file with at least one record in it.  This is required by the Survox Console.
    3. Deploy the study
  2. Via Command Line
    1. Navigate to the master <study>/<mode> subdirectory
    2. Copy the <master>_wc.qff to <master>.qff
    3. Copy the <master>.qff file to the QFF directory
      1. Because the worker specs refer to the master quota by using MASTERQUOTA= in the study header, Survent needs the <master>.qff file in the QFF directory.
    4. Copy the <master>.quo into each of the worker <study>/<mode> subdirectories
      1. Because the worker specs refer to the <master>.quo by using MASTERQUOTA= in the study header, this is required to compile the specs.
    5. Copy each of the worker specs into the worker <study>/<mode> subdirectories to compile
    6. Compile each worker study by typing in mentor <worker study>.qpx
    7. Make sure that each spec compiles cleanly before moving on to #3 below
      1. Fix any errors and recompile
  3. Via the Survox Console
    1. After the worker specs are compiled, the rest of the Project Setup can be done via the Survox Console.
    2. Upload the sample files to each of the worker projects
    3. Import the sample files to each of the worker projects
      1. Modify the phone parameters as necessary
    4. Select a look for each of the worker projects
    5. Deploy each worker project
    6. Configure the dialing rules for each of the worker projects in Manage – Study Control
      1. Dialing rules may be different depending on the type of sample
      2. For instance: Manual dialing for cellphone type sample
    7. Check the quotas under Manage – Manage Quotas on the Master study
      1. If only master quotas are used, all quota checking can be done in the Master study only
      2. If Non-Master quotas are also used within each of the workers, those quotas will need to be checked in each of the worker studies

NOTE: If any spec changes are required, you must follow the steps under #2 above for all changes.  You can update the live files using the Console after clean compiling of the modified specs.