queXS: Administration

# Questionnaire Creation and Management

### Adding a questionnaire

queXS relies on the LimeSurvey system to administer the questionnaire to the operator. 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

  - 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, for example: http://active.dcarf/quexs/rs_project_end.php

    - 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

- 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.

- 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 illicit 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

- Then click on “Submit query”

- Only fields that have at least one phone number will be added to the sample

### Assigning samples to questionnaires

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

- 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).

- 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.

- 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

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 AAPOR outcomes 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

# 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