Questionnaire Creation and Management

queXS 2.x.x : Linking queXS with Limesurvey

queXS relies on the LimeSurvey system to administer the questionnaire to the operator. Please ensure Limesurvey 2.0.6 or greater is installed, and the JSON RPC interface is enabled (under Configuration, Global Settings, Interfaces). Take note of the RPC URL from Limesurvey.

Once you have the Limesurvey JSON-RPC URL:

Browse to the queXS administration page
Select "System settings" -> "Questionnaire service RPC"
Enter in the details of the Limesurvey server as required
Save your settings

queXS will then query the Limesurvey server for a connection, if it is successful, it will save this connection, otherwise it will request for you to confirm the details entered.

queXS can connect to multiple Limesurvey installations simultaneously. If you have more than one installation you wish to connect with, simply add another in this section. Give them a unique description to identify the connections by.

Adding a questionnaire

In the queXS 1.x.x series, a patched version of LimeSurvey is included with queXS to aid in interoperability. Keep in mind that a single questionnaire in LimeSurvey can be added to queXS multiple times if necessary (eg once for testing, once for the live run).

Add questionnaire manually

Go to the queXS administration page
Click on the link: Administer questionnaires with LimeSurvey
Enter the LimeSurvey username and password
- By default the username is:admin and the password is: password
Use the LimeSurvey documentation to assist in creating a new questionnaire.
The following settings must be adhered to to create a successful questionnaire that
is interoperable with queXS (Note: As of 0.9.3 - these are the default settings)
- Under Presentation and Navigation
  - Format must be Question by Question
  - Template must be quexs
  - End URL must be a link to the rs_project_end.php file in your queXS
    installation directory. This can be achieved by entering the token: {ENDINTERVIEWURL}
  - Automatically load URL when survey completes must be Yes
- Under Notification and Data Management
  - Anonymous answers must be No
  - Enable Token-based answers persistence must be Yes
Within the text of questions, the following tags may be entered, which will be automatically filled at run time by the queXS system.
- {PERIODOFDAY} Either: morning, afternoon or evening
- {OPERATOR:FIRSTNAME} The first name of the operator
- {OPERATOR:LASTNAME} The last name of the operator
- {RESPONDENT:FIRSTNAME} The first name of the respondent
- {RESPONDENT:LASTNAME} The last name of the respondent
- {SAMPLE:xxxx} Where xxxx is the name of a column within the provided sample file (please use all UPPERCASE letters for compatibility across all versions)
- {APPOINTMENTDATE} The date of the next appointment (queXS >= 1.2.0)
- {APPOINTMENTTIME} The time of the next appointment (queXS >= 1.2.0)
- {APPOINTMENTNUMBER} The telephone number of the next appointment (queXS >= 1.2.0)
- {STARTINTERVIEWURL} The URL of the questionnaire proper (queXS >= 1.2.0)
From queXS 1.2.0, it is possible to specify Limesurvey questions of type "List: radio" and "List: radio (flexible labels) that have special queXS functions, such as creating an appointment when selected, or ending the current call with a specific outcome. These are most useful when using a Limesurvey instrument as your respondent selection module. Listed below are the tokens that can be used as the label text and that will be automatically replaced by queXS
- {OUTCOME:x} Where x is the queXS outcome id. This will be replaced by the outcome text. See the Outcome codes list for a listing of outcome codes by id
- {SCHEDULEAPPOINTMENT} This will bring up the schedule appointment screen when selected
A further enhancement in queXS 1.2.0 is the ability to update same information from the Limesurvey instrument. For this, you will need a question type of "Multiple short text". In each "answer" of the Multiple short text type, you can enter a token such as {SAMPLEUPDATE:xxxx}, where xxxx is the name of a column within the provided sample file. When the operator comes to this screen, they will see the contents of the sample record, and if they modify it, it will be updated in the sample.
Also newly available in queXS 1.2.0 are two new Limesurvey conditions. These are {TOKEN:CALLATTEMPTS} and {TOKEN:ONAPPOINTMENT}. These conditions are available in the Limesurvey conditions menu. The CallAttempts token returns the number of call attempts for the current case, therefore can be used for branching of the Limesurvey questionnaire based on the number of call attempts. OnAppointment returns 0 if the current call is not on an appointment, and 1 if it is. Again, this can be used to conditionally branch based on the current case appointment status.
Once the questionnaire is ready to run, it must be activated within LimeSurvey.
Also, a tokens table within LimeSurvey is required to be created after activating the
questionnaire.

Add questionnaire from queXML

Use the queXML tools website to convert your queXML file in to a LimeSurvey import file
Follow the instructions for Add a questionnaire from an existing instrument in Limesurvey

Add questionnaire from an existing instrument in LimeSurvey

When creating a new survey, use the Import feature
Import the LimeSurvey csv file produced by conversion from queXML or from an existing
installation of LimeSurvey
Make sure the settings for the questionnaire match those from the section above: Add questionnaire manually

Add questionnaire to queXS

Go to the Create a new questionnaire link in queXS administration
Enter a name for the questionnaire
Select the questionnaire from the list Select creation type
- A questionnaire created in LimeSurvey should appear under Existing
  questionnaire...
If the questionnaire is for testing, make sure to select the Testing box. This will ensure that all calls can only be made internally to operators no matter what sample is assigned to a questionnaire.
In queXS 1.2.0, it is possible to use a separate Limesurvey instrument as the respondent selection module. In this case, when creating the questionnaire, 2 questionnaires will be created in Limesurvey. These need to be created and activated as described above separately, but the respondent selection module will appear when the operator begins a call, and then may move on to the questionnaire proper, based on the responses given
"Allow for respondent self completion via email invitation" will allow interviewers to send an email to the respondent with an invitation link to complete the quesitonnaire online. If this option is selected, you must enter a URL in the box "URL to forward respondents on self completion (required)". This is the URL the respondent will be directed to when the questionnaire is complete. You will need to select if the questionnaire is displayed all in one page, section by section or question by question. You are also able to select from available Limesurvey templates as to how the questionnaire is displayed to the respondent when self completing. The display and template options only apply when the respondent is self completing.
If there is to be respondent selection for the questionnaire, enter it in to the boxes. You may use the tags listed above
- Respondent selection introduction is the first text read by the operator to whoever answers the phone. This is used to find the respondent you are after.
- Respondent selection project introduction is used to tell the respondent about the project, and to enlist their cooperation
- Respondent selection callback (already started questionnaire) is read to the respondent if they have already started the questionnaire and are being called back.
- Message to leave on an answering machine is a message to leave on the answering machine if allowed by the system.

Adding a sample

Sample list formatting

queXS requires sample lists to be in CSV form. The first row should contain the name of the column. Most statistical packages, and Microsoft Excel can export lists in CSV form. The minimum required for a sample file is a single column containing a phone number. A sample list containing the name of the respondent should be formatted with the first name and last name of the respondent is separate columns. For example:

firstName	lastName	Number	Sex
Fred	Jones	03 1234 5678	M
Mary	Jones	03 1234 5678	F

Add the sample

Once the sample list is saved in CSV form, it can be imported in to queXS

Go to the page: Import a sample file (in CSV form)
Browse for the file and give the sample file a descriptive name
Click on Submit
A page will appear containing a list of all the columns in the sample file, along
with a checkbox indicating whether the column should be imported, the name of the column
and the type
For each column, select whether it is to be imported, check the name, and select the type of data contained in that column. For example:
- String: A field that should be imported as is and not to be specifically used by queXS. (but will be available when using the {SAMPLE:xxxx} tag)
- Phone number: A phone number
- Primary phone number: The main phone number for this respondent. This must be selected for one and only one column
- State: The state (currently only Australian states loaded, either in abbreviated form such as: VIC, NSW or full such as Victoria or New South Wales)
- Postcode: The postcode (only Australian postcodes loaded)
- Respondent first name: The first name of the respondent
- Respondent last name: The last name of the respondent
- Email address: The email address of the respondent
You can also select whether the field will be available for interviewers to view when looking at information about the respondent.
Then click on Submit query
Only fields that have at least one phone number will be added to the sample

Sample management

Sample management displays a list of sample files accessible in the queXS system. It also allows for disabling a sample file which will stop it displaying in available samples (but will not delete the sample).

Deidentification of the sample is used to delete fields in the sample after data collection is complete. This may be a requirement of your project so that it isn't possible, even with access to the raw queXS database to link a respondent to a questionnaire.

Operator viewing permissions allows you to choose which fields are viewable by interviewers.

Assigning samples to questionnaires

Use the Assign samples to questionnaires link to assign a sample to a questionnaire.

Note: It is safe to un-assign then re-assign a sample to the same questionnaire. Duplicate cases will not be created based on the same sample record. When you un-assign a sample, new cases will not be created from that sample. When you assign it again, new cases will be created but only new cases that have not already been created.

Select a questionnaire to operate on
Select the sample to add from the list
Choose from the following
- Max calls (0 for unlimited): Maximum number of calls (a call is a call to any number available in the sample)
- Max call attempts (0 for unlimited): A call attempt is a chance an operator has to call any or all of the numbers for a particular case
- Number of answering machine messages to leave per case (0 for never): How many answering machine messages to leave
- Select from sample randomly? (otherwise sequentially): The method to select from the sample list when creating a case

Assigning pre-filled questions

A pre-filled question is a question within the questionnaire that has data filled before the operator begins collecting data. The pre-filled data could be static (the same for each case within the questionnaire) or come from information already available in the sample.

To pre-fill a question within the questionnaire, go to the link: Set values in
questionnaire to pre fill
Select the questionnaire, then the question to pre fill
Enter in either the static information, or sample information using the tags listed above
To remove the pre-fill, simply click on it.

Adding operators to the system

queXS relies on an underlying authentication system (such as Apache Basic Authentication) to handle authentication of users. Once they are authenticated, queXS uses the username of the operator to determine who the operator is, and therefore how to assign work to them. This means that queXS needs to know the authentication system username (username only, not password) of each operator on the system and some other details if using Voice over IP (VoIP). In addition, queXS (from 1.9.0) supports XMPP/Jabber chat from interviewers to a supervisor. To enable this feature, each operator must have a XMPP/Jabber username and password assigned along with chat enabled.

To add an operator to queXS, click on Add operators to the system
Enter the system username
Enter the first name of the operator, and the last name of the operator
Enter the timezone where the operator is located in (this list may help) it should be in a format such as Australia/Victoria
The telephone extension number must be unique for each operator, and is necessary if using VoIP. This is the extension to log in as to the VoIP system. queXS will send the extension number as the password when logging on. If using VoIP integration with Asterisk, you will need to specify the type of extension along with the extension number, for example SIP/5000 or IAX/5000 (for the extension number 5000)
The XMPP/Jabber username, password and "chat enabled" fields allow for the entering of chat details. Create a Jabber/XMPP account for each operator separately and enter the username and password details here to allow them to use the chat function
The normal interviewer, supervisor and refusal converter checkboxes automatically assign skills to the operator. See the Assigning skills to operators section for a description of operator skills

Assigning operators to questionnaires

When an operator is assigned to a questionnaire they will be assigned work from that questionnaire. An operator can be added or removed from a questionnaire at any time.

To assign an operator to a questionnaire, go to the link: Assign operators to questionnaires
Check the box for the operator and the questionnaire, then click on Submit query to confirm it.

Assigning skills to operators

Assigning skills to operators is done in a similar fashion to assigning operators to questionnaires. The following skills are available:

Temporary outcomes
- These are normal cases, such as ones that have never been called, or have
  a previous outcome such as No answer
Supervisor outcomes
- Where a case has been referred to the supervisor
Refusal outcomes
- Where the case has been refused
Final outcomes
- Where the case has a final outcome, such as complete, final refusal, disconnected number
Appointments
- Where an appointment has been made

Use the Modify operator skills tool to assign the appropriate skills to each operator. A normal interviewer has Temporary and Appointment assigned to them.

Creating/modifying shifts for a questionnaires

queXS will usually only assign work to operators if they are assigned to the questionnaire, have the appropriate skill assigned to them, and finally that there is a shift available at the current time for the
questionnaire. Defining shifts allows for appointments to be restricted to times when operators will be available, and to restrict work to specific hours. It is desirable to add as many shifts as you know will be run in advance so that operators will be able to schedule appointments in them. But conversely, remember not to add shifts if they will not be run, as appointments may be made for those times. The shifts listed by default are taken from the shift_template table, and can be modified by a system administrator.

To assign shifts to questionnaires, use the Shift management (add/remove) tool
Select the questionnaire to create a shift for
The current year and week of the year are selected, but these may be changed to suit when the shifts need to be added
Confirm the shift start and end times, and dates, and select the Use shift checkbox if you wish to include that shift for this questionnaire
Click on Submit changes to confirm your shift selection

Note: If shifts do not save - it is likely that your mySQL server does not havetime zone support installed Once you have completed all the steps in the Questionnaire Creation and Management section, the system should be ready to execute questionnaires. The following sections describe information about the progress of the questionnaire, and functions for the supervisor to modify erroneous outcomes or handle cases where the operator was unsure about what outcome to assign

Questionnaire progress

Display future appointments

Clicking on this link will display a list of all appointments in the future.

Questionnaire outcomes

By selecting a questionnaire, a list of AAPORoutcomes and rates will be listed.

Operator performance

Performance of operators is split in to completions per hour and effectiveness. Effectiveness is the ratio of how often an operator is on a call while a case is assigned to them.

Supervisor functions

Assigning outcomes to cases (and calls)

An operator may incorrectly assign an outcome to a call, or have assigned a case to be reviewed by a supervisor. A supervisor can then modify the outcome of a call and/or the outcome of the case.

To modify the outcomes of calls or cases, go to the Assign outcomes to cases link
Select a case
- If a drop down box is visible, there are cases assigned to the supervisor in it that can be dealt with. If so, you can select one of the cases from the drop down list
- A box to enter a case id is also available
Confirm that the project and sample is correct for the case you are expecting
A list of calls made for that case will be listed
- Clicking Edit on the call list will allow you to change the outcome of the call
- Please note that changing the outcome of the call will not change the outcome of the case automatically
Notes are listed
- It is recommended to add a note to the case if any changes are made so the operators
  will not be confused about any possible inconsistencies with the case
A case outcome can be set
- This is the current outcome for the case. This determines how cases are made
  available to operators

Creating shift reports

A shift report is filled in by the shift supervisor to detail any notes about a particular shift.

Searching the sample

A supervisor can search the sample to find particular records to either remove from the sample, therefore not ever be selected as a case, or if a case has already been assigned to be able to see what calls have been made to the case and modify the outcome if necessary (using the Assigning outcomes to cases tool).

To search the sample, click on Search the sample
Select the sample you wish to search within
Enter the search term in the box and click Start Search
A list of matching searches will appear
- If a sample record has already been assigned to a questionnaire (become a case), then
  clicking the assigned to questionnaire link will take you to the Assigning outcomes to
  cases tool for viewing or modifying the outcome of the case
- If a sample record has not yet been assigned to any questionnaire, then the link No
  cases yet assigned will appear. By clicking this link, the record will be deleted from
  the sample.
  - WARNING: You cannot recover a deleted record, so be careful!
- If nothing in the sample matches your search criteria, no records will be
  returned

Case status and assignment

This is a view of the cases currently available in the system, and when they will be available to be called. You can use this to get an overview of what cases are currently available, and also select one or more of them to be called by an operator right away. This function can be useful when there are only a handful of cases left in a sample and manual scheduling is desirable.

Bulk appointment generator (from queXS 1.5.4)

This function allows for a CSV file to be used to generate appointments by caseid. This may be useful where you have call back information from a previous study or alternate system to queXS and need to schedule a future appointment.

Client Management

A client view of the project is available in the client subdirectory of the queXS installation. If this URL is made available publicly, and each client is assigned a system username and password as for operators, then clients can be added to the system and assigned to questionnaires. Each client will then see a progress report of each questionnaire assigned to them when visiting the client page and entering in their credentials.

Adding clients to the system

Follow the link Add clients to the system
Enter in the system username of the client
Enter their first name and last name
Enter the timezone the client is in (or leave as default if unknown)
Click Add user to add the client to the system

Assigning clients to questionnaires

Follow the link Assign clients to questionnaires
Check the box that intersects the client's name and the questionnaire
Click on Submit query to confirm the assignment

System Settings

Setting the default timezone list

Use this tool to set the default timezones available to operators. This list may help). It should be in a format such as Australia/Victoria

Setting the default shift times

The "Add Shift" tool relies on the default shift times in the queXS database to display shift times for each project. This tool will modify the default shift times. The times should be entered in 24 hour time, with seconds. For example, 10pm would be: 22:00:00

Setting the call restriction times

These times restrict when calls can be made to a respondent. queXS will make sure that a respondent is not called outside the hours set by this tool (in respondent time). This is useful for complying with local regulations on allowed calling times

Supervisor chat (from 1.9.0)

Enabling supervisor chat will allow operators with an XMPP/Jabber account to chat with a supervisors XMPP/Jabber account. You will also need to specify a BOSH URL. Code and Life have a good article describing setting up an XMPP/Jabber server with BOSH enabled. In addition, you will need to specify the XMPP/Jabber id of the supervisor (in the case of GMail chat, this is just their email address).

VoIP

Monitoring VoIP

When using queXS with the Asterisk VoIP server, it is possible for call outcomes (such as the person called hanging up, or a busy signal received) to be monitored by queXS so the operator will not have to do it manually.

This requires a process to be run on the server in the background.

In installations of Version 0.9.3 and below, do the following:

Open a shell to your web server
Navigate to the voip directory inside the queXS installation
Execute the following commmand: php voipwatch.php &

In Version 0.9.4 and greater, navigate to the page "Start and Monitor VoIP" in the Administration section (This will only appear if VoIP is enabled) - then Click "Start monitoring". You may return to this page at any time to stop the monitoring process, or to see the progress of monitoring.

queXS Administration Manual