### Assigning data to clients: the use of client-accessible parameter files.

With a focus on how to assign client's their initial data

Client accessible parameter files (CAP files) are the main mechanism dSurvey uses to transmit information between administrator and participants. This document describes their usage.

#### If you use automated instrument creation, or the create an instrument wizard

If you create your instrument using Create An Instrument wizard, or the Create & modify an instrument utility, (botb if these are avaialble via the dSurvey administrative page), you do not have to worry about the details described below -- you just specify some parameters when creating the instrument, and the appropriate control panels and descriptor files will be created.

Nevertheless, there are times when you may wish to tweak these automatically created files. In which case, read on!

- Introduction
- If you use automated instrument creation

- Background
- Participant specific data
- Assigning reference data to clients

- Choosing how a clientID is determined

- (a) Assigning reference data: control panel assignation
  Assigning reference data: control panel assignation -- assigning a REFID
- (b) Assigning reference data: Client-side assignation
  Assigning reference data: Client-side assignation -- assigning a REFID
- (c) Assigning reference data: explicit assignation

- Creating client-accessible parameter files: participant input

- A note on open-ended surveys

- Assigning participant-specific data

#### Introduction

Client accessible parameter files (CAP files) are ...

1. created, and re-created by the control panel -- using instructions that can be customized in the control panel program for this session
2. saved on the web-server (by the control panel)
3. when needed, they are read by each client. For example, when the participant starts the session, or when a new round is started.

CAP files can contain several kinds of parameters:

1. `General` parameters. These are the same for all participants
2. `User`. These are client-specific records. Each record will have the same variables, but the values of these variables will differ.
3. `Reference` table. Similar to `user`, but records are not explicitily assigned to particpants.

CAP files are created using information stored in several internal control panel databases:

1. generalData: used to create the general parameters
2. userData: used to create client-specific parameters
3. referenceData: used to create the reference table

These internal internal databases are either read from administrative parameter files, or constructed by the control panel

This documentation describes how the control panel is used to create these CAP files from the control panel's internal databases.. In particular, several `<DO>` actions will be described. Note that the discussion here is somewhat simplified: for the details, see the example control panel program.

#### Background: assigning data to participants

A basic problem faced by dSurvey is how to automate the process of assigning client-specific parameters to participants. This data will often vary across participants.
For example, a `COST` variable might be used in an auction experiment, and this `COST` variable varies across participants in the experiment.
And to make things more complicated, the participants might be anonymous -- so that assignation of values may not be able to use information about the participants (such as their `name`).

Participant specific data

One way to solve this problem is to force participants to choose a `clientID` when they join, and then directly associate this data with a `userData` record.

This participant chosen clientID must be a a unique value that matches a record stored in a (CAP) file. So using participant specific data means that each participant must correctly enter his clientID.

Note: If you use participant selection, the following discussion on reference data can be ignored. Basically, instead of using `reference` data, one should explicitily code `<user>` data, with `ids` that match the clientIds chosen by participants. This means that if the participant choses a clientID with no match in the `user` section (of a CAP file), he will not be able to read his client-specific parameters.

Assigning reference data to clients

In the more likely case that you can not assume such discipline, dSurvey solves this problem through the use of `reference` data.

- `Reference` data consists of multiple records
- each record contains the same variables.
- The values of these variables can differ across records.
- The records are identified by a unique `record id`.

The idea is to match a `reference` record to a participant -- to assign values from a record in the `reference` data to a particular participant. And the way to do that is to somehow assign a participant-specific `REFID` (`reference ID`) to the participants, and use this REFID to identify the `record id` of the desired `reference` record.
For example, if a participant's `REFID` is 22, it would be matched against a record in the `reference` data that has a `record id` of `22`
This raises a problem: where to find a participant's `REFID`? After all, when the possibly anonymous participant joins, dSurvey typically has very little information about him (i.e.; just his `name`).

dSurvey provides several means of solving this problem. We call them:

1. Control-panel assignation. The control panel assigns each participant a `REFID`
2. Client assignation. The client constructs a `REFID`.
3. Explicit assignation. Using the participant's `name` (or perhaps some other participant supplied information), a particpant's `REFID` is extracted from a specially constructed database.

What are the differences?

- Control-panel assignation. Assignation of the `REFID` must be done at a discrete moment in time. In particular: after all the participants have joined, the control panel assigns each one a `REFID`.
  Note that is quite legal to assign the same `REFID` to different participants. In such a case, the client-specific parameters (well, those provided via the client-accessible parameter files) will be the same.
  This means that after joining, participants must wait for the control panel to do its magic. And the control panel must, after doing the assignations, somehow tell the participants to stop waiting.

- Client assignation. The client has to construct a `REFID` without consulting the administrator. This occurs when each participant joins. That is, the control panel is not involved in assigning `REFID`s.

- Explicit assignation requires extensive setup -- the survey administrator must construct a database that matches users to a `REFID`, typically using a set of `names` that will be allowed to enroll in the session. This database will be available to the clients -- when a participant joins, the client wil extract the appropriate `REFID`.

Reminder: if participant specific data is used, the participant must enter a unique, and valid, `clientID`. And this `clientID` is used instead of a REFID.
What are the advantages and disadvantages?

- Control panel assignation. dSurvey supports several methods of assigning a `REFID`. However, since `REFID`s are assigned to all participants at once, it is cumbersome to deal with participants who are late (who join the session after the control panel assignation has occured). That means that control panel assignation does not work well with open ended surveys.

- Client assignation. Since this occurs when a participant joins, client assignation is well suited for open ended surveys. However, the methods of assigning a `REFID` are not as numerous (compared to control panel assignation).

- Explicit assignation. You have complete control over the parameters assigned to a participant, and open ended surveys are supported. However, anonymous users are no longer supported. Prticipants must supply a `name` known to the administrator, in the sense that this name can be used to find a `REFID` in a database contructed by the administrator.

- Participant specific data. No need to assign a REFID, and the administrator does not need to monitor. But the participant must be told (say, verbally) what `client id` to enter.

Summarizing ...

- When a participant joins a session, he is somehow granted a unique clientID.
- Before the session starts, he might also be assigned a REFID.
- If a REFID is assigned: the REFID can be used to assign data to the client by using a record from a reference table (provided in the CAP file).
- If a REFID is not assigned: the client can use his clientID to read data from a user database (provided in the CAP file).

#### Choosing how a clientID is determined

The `ID_WHICH` session descriptor variables is used to control how a `clientID` is determined. The values can be:

- 0 = ... client-assigned id (id is randomly generated on each client's machine).
  This is typically used with control panel assignation of reference data.
- 1 = ... when a participant joins a session, obtain id from the server.
  This is typically used with client side assignation of reference data
- 2 = ... the participant enters his ID.
  This is typically used when reference data is not needed (when participant specific data is used).

Note that choosing how a clientID is determined, and choosing how (or if) reference data is assigned, are independent-but-related decisions.

(a) Assigning reference data: control panel assignation
Consider the following outline of required steps one takes when using control panel assignation to assign reference data to a client.

1. Participants are allowed to enroll. At some point in time, this enrollment is curtailed. Thus, the survey is not open ended.
2. The control panel retrieves (from the web server) `REFERENCE`, and `GENERAL`, data contained in administrative parameter files. These are used to create the referenceData and generalData internal databases.
3. The control panel retrieves the list of participants (which also contains each participant's clientID, and may contain other participant specific information).
4. Using one of several methods, a `REFID` is assigned to each participant in this list.
5. A matching record in the reference data is found (by comparing this `REFID`, to the `record ids`).
6. Using this matching record, the control panel will create variables (for this client) in its `userData` database

   Once these steps are completed for all participants,

7. One, or more, client-accessible parameter files (CAP files) are created. They can contain `GENERAL` and `USERS` data for each participant. USERS data will be generated for all clients, with each record in the USERS data identified by clientID.
8. This data is uploaded to the web-server, where it can be retrieved by the clients. Clients will read the `USERS` section, and by using his own `client id`, will extract his data.

The above is accomplished through the control panel. In particular, by proper coding of `<DO>` actions within a control-panel-program, where these `<DO>` actions can be invoked at the administrators discretion.
In what follows, we describe the tasks (within a `DO`) used to implement the above steps.

<reset /> | This will reset (delete) a number of internal databases (including the generalData, referenceData, and userData). This can be useful if you need to reload all the internal databases, say if things get hopelessly confused.
<join allow="0/1" /> | Enable/disable acceptance of new participants. `allow="0"` : do NOT allow new participants to join `allow="1"` : curtail enrollment -- do allow new participants to join If allow is not specified, an error will occur `join allow="1"` should be enabled as soon as participants are ready to join. Then, after everyone has enrolled, `join allow="0"` should be used. As an alternative to `join`, the participants generic-control-panel options can be used to enable/disable acceptance of new participants.
<getParams > xmlFile </getParams> | Retrieve a session-specific administrative parameters file, and store the parameters specified therein in the generalData, userData, and referenceData internal databases. It is not unusual to specify more than one `<getParams >`: one may contain `GENERAL` information, and one may contain `REFERENCE` data. In most cases, administrative parameter files will not include any `USERS` data. `xmlfile` should specify a file name, with no path information, that exists for this session. Typically, these are specified in the instrument descriptor file used to generate this session.
<getParticipants /> | Retrieve (from the web server) a list of the current participants for this session, and save to an internal database. Each participant is identified by a unique clientid. Note that this list is augmented whenever a client joins the session (the control panel reads, but does not write, to this server-side database). `getParams` and `getParticipants` can be specified in any order. `getParticipants` should be called after enrollment of new participants has been disabled (say, by using `<join allow="0" />`). Otherwise, you risk working with a out-of-date list of participants.
<assignRefID /> | Assign a `REFID` variable to each participant. The HOW_ASSIGN variable is used to dictate the method used. `assignRefID` should be after `getParams` (to retrieve `REFERENCE` data) and `getParticipants` (to retrieve an up-to-date list of participants). `resolveReference` should be after `assignRefID`.
<resolveReference /> | Using the `REFID` variable, add variables from referenceData to client-specific rows in userData The basic idea is that data in the referenceData internal database is used to populate participant specific variables, which are stored in the userData database. In particular, after `assignRefID` is used to create a `REFID` for each participant, the value of this `REFID` is used as the index to a data record in the referenceData database. The variables (and their values) in this record are then copied to the participant's record in the userData database. `resolveReference` should be used after `assignRefID`, and before `postCAP`. It is completely legal for more than one participant to have the same value of the `REFID` -- in such a case, all participants with the same `REFID` will be assigned the same values.
<addParticipantData pvar= userVar <</addParticipantData> | Optional. Copy data from the `user` database to the `currentParticipants` database. Variables in the currentParticipants database can be written to CAP files as address information.
<postCAP type="atype"> <general > varlist </general> <users > varlist </users> <reference > varlist </reference> <</postCAP> | Create a client-accessible parameters (CAP) file, and upload it to the web-server. The web-server will store this file in a web accessible location. Note that this is typically done after disallowing new entrants (using `join allow="0"`). `type="atype"` : atype can be `SESSION` or `ROUND`. The clients, per instructions in the specification file, can retrieve either one, or both, of these. Typically, `SESSION` CAP files are only read when a session starts. `ROUND` CAP files typically contain only newly computed, or recently changed, `general` or `users` variables (say, values computed just before a new round starts). `<general > varlist </general>` : Specifies what variables (from generalData) to include in the `general` section of the CAP file. Use `<general > * </general>` to include all the generalData variables (and address variables used by dSurvey's message feature). `<users> varlist </users>` : Specifies what variables (from userData) to include in the `users` section of the client-accessible parameters file. Use `<users > * </users>` to include all the userData variables (for all the participants). Actually, `varlist` can be quite complex -- see the description of <postCap>. `<reference > varlist </reference>` : Rarely used with control-panel assignation. Specifies what variables (from referenceData) to include in the `reference` section of the client-accessible parameters file. Use `<reference > * </referencel>` to include all the referenceData variables. Note: when using `control panel` assignation), `<reference>` is not recommended -- it just adds redundant information to the client-accessible parameter file (information that is already in the `<USERS>` section). You can specify more than one `postCAP`: say, one to save `SESSION`,and one to save `ROUND` variants of the client-accessible parameters file.
<takeSnapshot /> | Take a snapshot of the session's current internal databases (generalData, userData, referenceData, and data on participants), and save it to a file on the web server. This snapshot can be reloaded, a handy trick if the browser you are running the control panel on should crash.

#### Assigning reference data: control panel assignation -- assigning a REFID

The assignment of a reference ID is controlled by the value of the `HOW_ASSIGN` session descriptor variable.

Supported values for `HOW_ASSIGN`:

- Note: in what follows, `REFERENCE` is a short hand for: the `REFERENCE` section in an administrative parameter file. Alternatively, one can think of `REFERENCE` as the internal referenceData database, a database constructed by reading this `REFERENCE` section.

NONE | Do not assign reference data. Use this if their is no need to assign variables (and their values) from the `REFERENCE` dataset to participants.
0 | Sequential assignation of data. The referenceData record used (to populate a participant's record in userData) is chosen in in order of joining. That is, the first row read from `REFERENCE` is used for the first joiner, etc etc etc. If the number of "joiners" exceeds the number of rows, a reference id of `0` is used.
NAME=rNAME | `rName` must be a variable defined in `REFERENCE` For each user, the particpants `NAME` (as entered when he joined the session) against a REFERENCE row with the same value of its `rName` variable. For example: `NAME=REFNAME` Matches are case InSensitive, with spaces stripped. If a match (the users `name` matches a `rName`) occurs, the corresponding row is used. If a match does not occur, a reference id of `0` is used. Note there are several other methods for Assigning participant-specific data (such as explicit assignation).
STOP | Once the number of joiners equals the number of rows in the `REFERENCE`, a `-1` is assigned, and an error message might be displayed.
CYCLE | Similar to `0`, except once the number of joiners equals the number of rows in the reference database, the program goes back to the top: the next joiner gets the first row, etc.
RANDOM | A random row is always assigned (regardless of how many joiners there are) This means that everyone could get assigned the same row (unlikely, but possible)
RANDOM_NOREP | A random row is pulled without replacement. This means that when all rows in the reference dataset have been used, a "-1" is used

- The `0` reference ID is ALWAYS used as a default. Thus, if 11 rows are defined in the reference dataset, and one of them has a reference id of 0, then only 10 rows are available for assignation to specific participants.

(b) Assigning reference data: Client-side assignation
For client assignation, the control panel does much less work. Consider the following steps:

1. The control panel retrieves (from the web server) REFERENCE, and GENERAL, data contained in administrative parameter files. These are used to create the referenceData and generalData internal databases.
2. One, or more, client-accessible parameter files are created. They can contain `GENERAL` parameters, and `REFERENCE` data for each participant.
3. These parameter files are uploaded to the web-server, where they can be retrieved by the clients.
4. Participants are allowed to enroll. If enrollment is not is curtailed, then the survey is open ended
5. When a participant enrolls, he uses some session-specific information to generate a `REFID`
6. The client retrieves the client-accessible parameter files.
7. A matching record in the reference data is found (by comparing this `REFID`, to the `record ids`) in the `reference` section of the client-accessible parameter files.
8. Using this matching reference record, the client will create its client-specfic data.

The above is accomplished through the control panel, and through client actions. That is, the control panel has less to do.

<reset /> | As above.
<getParams saveRefMax="1"> xmlFile </getParams> | Similar to above. The `saveRefMax` attribute designed to work with the `<REF_MAX>READ</REF_MAX>` session descriptor variable. To use `saveRefMax` with `REF_MAX` you must: call `<getParams >` before the first participant joins. include a `saveRefMax="1"` attribute in the `<getParams >` Note: `<REF_MAX>READ</REF_MAX>` is used if the number of reference records may change. The `saveRefMax="1"` tells the server to record the maximum `record id` to a server variable (`maxRecordId`) which the clients will read if `<REF_MAX>READ</REF_MAX>` is specified (in the instrument descriptor file).
<postCAP type="atype"> ... <</postCAP> | As above. However, `<REFERENCE>` must be specified. typically `<USERS>` is not specified. Note: with client-side assigination, `<assignRefID>` should not be used.
<join allow="0/1" /> | As above, but if your survey is open-ended, you do not need to curtail enrollment (you don't need to use a `join allow="0"` before `postCAP`).
<getParticipants /> | As above. Be sure to call `getParticipants` before `resolveReference`. Note that the list of participants includes both the clientID, and the REFID, for each participant. Note: `getParticipants` is not strictly required when using client-side assignation, but can be handy (see the description of `resolveReference` for the details.)
<resolveReference /> | Under client-side assignation, a client will determine his client-specfic parameters by using the `refid` he generated (or, as noted below, was explicitily assigned) to read a record from the `reference` table contained in the client-accessible parameters file. Thus, using `resolveReference` to populate a `user` record (in the CAP file), and using `getParticipants` to update the current participants database, is not strictly necessary. However, populating the `userData` control panel database may still be important. If this is the case (say, client specific parameters are needed to compute round results), `resolveReference` can be used. Basically, when `resolveReference` is invoked, the `refid` of all current participants is used to populate the `userData` with values extracted from the `referenceData`. Be sure to use `getParticipants` before `resolveReference` Upon choosing or being assigned a `refid`, the client always report it to the server. Thus, the list of current participants, that is maintained on the server, contains the `refids` even when the `refid` is client-side assigned. Reminder: `resolveReference` uses `reference` data that you is retrieved with `getParams` Note: reference data is read only once! `reference` records are used when the client enrolls. After that, they are not used again. However, `user` records may be read every time a client-accessible parameter file is read. Say, at the beginning of a new round. Thus, information in a `user` record can be used to update client-specific parameters, even if these were initially determined using client-side assignation.

#### Assigning reference data: Client-side assignation -- assigning a REFID

As with control panel assignation, the `HOW_ASSIGN` session descriptor variable is used to specify how a REFID should be assigned.

Also, the `REF_MAX` session descriptor variables must be specified.

- If `REF_MAX` is `0`, then `control panel assignation` is used.

- Otherwise, `client side assignation` is used.

  Example: `<REF_MAX>20</REF_MAX>`
  Example: `<REF_MAX>READ</REF_MAX>`

- If `REF_MAX` value is `READ`, clients will read a server variable that contains the value of `REF_MAX`. As noted above, this does require using a `saveRefMax="1"` attribute in `<getParams>`.

  or...

- The `REF_MAX` value should equal the maximum value of the `records_ids` specified in the `REFERENCE` section of the adminstrative parameters file(s).
- In either case: using a non `0` value for `REF_MAX` implies that the `record ids` (for rows in the `REFERENCE` section) should have values that are consecutively numbered between 1 and the `REF_MAX` value. The advantage of `READ` is that this value can be unknown at the time you create the control panel (say, at a later date you might add new records to the reference data file).

`HOW_ASSIGN`, when used with client assignation, can take three values:

NONE | Do not assign reference data to participants
CYCLE | If the `clientID` was obtained from the server (if ID_WHICH=1), REFIDs will be assigned sequentially, and will cycle back to `1` when the REFID hits `REF_MAX` If randomly generated `clientID` is used (if `ID_WHICH=0`), a more-or-less random REFID will be generated, with a value between 1 and `REF_MAX`
RANDOM | A random value of `REF_ID` is generated (between 1 and `REF_MAX`). This means that everyone could get assigned the same record from the reference data (unlikely, but possible)

(c) Assigning reference-data: explicit assignation
Explicit assignation is just a variant of client side assignation. Instead of using `HOW_ASSIGN` (and `REF_MAX`), the participant's `name` is used to explicitily assign a `REFID` to the participant. This requires modifications to the `ALLOWED_USERS` parameter (in the session descriptor file ).

Refering to the above steps, only step `v.` changes -- `HOW_ASSIGN` and `REF_MAX` are no longer used.
Instead, you have to carefully specify `ALLOWED_USERS`.

Note there are several other methods for Assigning participant-specific data

Creating client-accessible parameter files: participant specific data
Participant specific data requires work by the participant, and setup in the `<users>` section of the administrative parameters file(s).

1. The control panel retrieves (from the web server) USER, and GENERAL, data contained in administrative parameter files. These are used to create the userData and generalData internal databases.

   This userData must contain records (`<user> ... </user>`) with an `id` attribute that matches the `client IDs` that the participants have been instructed to enter.

   That is: since the participant enters an id, there is no need to assign a reference ID. But one has to make sure that these participant entered IDs can be matched to records defined in userData.

2. One, or more, client-accessible parameter files are created. They can contain `GENERAL` and `USER` data for each participant.
3. These parameter files are uploaded to the web-server, where they can be retrieved by the clients.
4. Participants are allowed to enroll. If enrollment is not is curtailed, then the survey is open ended
5. When a participant enrolls, he enters his `client ID`
6. The client retrieves the client-accessible parameter files. Clients will read the `USERS` section, and by using his own `client id` (the one he entered), will extract his data.

The above is accomplished through the control panel, and through client actions. That is, the control panel has less to do.

<reset /> | As above.
<getParams > xmlFile </getParams> | As above. Except that rather than containing `reference` data, the administrative parameters file should contain `user` data.
<postCAP type="atype"> ... <</postCAP> | `<USERS>` must be specified typically `<REFERENCE>` is not specified. `resolveReference` and `assignRefID` should not be used. If they are used, it is difficult to predict just what values will be assigned to the client; since values assigned using a `refid` might overwrite values explicitily contained in a `user` record. If your survey is open-ended, `<getParams>` and `<postCAP>` should be executed before the first participant joins.
<join allow="0/1" /> | If your survey is open-ended, you do not need to curtail enrollment.

Notes: | `HOW_ASSIGN`, and `REF_MAX`, are ignored. The ID_WHICH session descriptor variable must be set to `2`

Note there are several other methods for Assigning participant-specific data

#### A note on open-ended surveys

Control panel assignation does not work well with open-ended surveys -- since assignation of data (from referenceData to userData databases) is meant to occur after all the participants have joined. In an open ended survey, participants may come and go as they please, with some participants concievably finishing before others begin.

Consider this example of using control panel assignation in an open-ended survey ...

1. N participants join, and client-accessible databases (that contain USER data for these N participants) are generated.
   The session then is started, and these N participants happily partake in the survey.
2. You (the administrator) keep the survey open -- you do not disable enrollment.
3. A new participant joins. Since the survey has started, his client will immmediately start the survey, and retrieves the client-accessible parameter files. However, `USER` section contains no information for this client. Problem!

So, solving this problem requires use of either:
- client, or explicit, assignation of reference data
- Using participant specific data
Recommended settings for anonymous open-ended surveys (parameters assigned to participants are participant specific) ...

Values set in the session descriptor file
`ID_WHICH=1` | A client ID will be assigned by the server
`REF_MAX=READ` | Clients will read a server variable that specifies the number of reference records
`HOW_ASSIGN=CYCLE` or `HOW_ASSIGN=RANDOM` | A reference ID will be assigned by order of enrollment, or randomly (with replacement)
Actions specified in the control panel file
`<getParams saveRefMax="1"> xmlFile </getParams>` | A variable will be saved on the server that specifies the number of reference records (this is the variable read if `<REF_MAX>READ</REF_MAX>` is specified). Note that `getParams` must be called before the first participant joins the session.
`<postCAP >` | `<REFERENCE>` must be specified. typically `<USERS>` is not specified.
`<join allow="0/1" />` | You do not need to curtail enrollment, but you can if desired.
`<getParticipants>` and `<resolveReference>` | These should be used if you process & use submitted values during the course of the session (rather then just collect submitted data after the session is closed)

#### Assigning participant-specific data

dSurvey provides several means of assigning data to participant specific data, using some kind of identifying information provided by the participant.

These are several ways of doing this..

USER parameter files | Reference-data parameter files are not specified. Instead, you must specify user-data parameter files. Each entry must be identified using an id that are specified. For example: <user id="clientID1">val1,...</user> The participant supplies a unique clientid when joining. This requires setting (in the session descriptor file): ID_WHICH=2. If `ID_WHICH=2` is specified, than the generic join-a-survey page will include a field for entering the clientid. `HOW_ASSIGN=0` and `REF_MAX=0` (actually, it doesn't matter what their values are).
ALLOWED_USERS file | The `ALLOWED_USERS` variable (or file) can be used with either control or client assignation (hence can be used with either close or open-ended surveys). The participant enters a name (and possibly a password). The ALLOWED_USERS session specific parameter is set to either: `ALLOWED_USERS=FILE` and the ALLOWEDUSERS.XML session-specific parameter file is modified. `ALLOWED_USERS=username:password=refid ...` (a space delimted list of user info words). In either case ... The `refid` must point to a `RECORD` in the reference-data set (with an `id` equal to the `refid`. passwords are not necessary (i.e.; to not requre a password, set the `password` to be 0). If you do want to require a password, be sure to set `USE_PASSWORD` (in the session descriptor file) to a non-`0` value. `ID_WHICH=1` or `ID_WHICH=0`. Reminder:`ID_WHICH=1` is typically used for open-ended surveys. `HOW_ASSIGN=0` and `REF_MAX=0` (actually, it doesn't matter what their values are).
Name in reference parameter files | This can only be used with control-panel assignation (thus, it is not meant to be used for open-ended surveys). Set `HOW_ASSIGN= NAME=REFNAME` Set `ID_WHICH=0` (non-opened survey) In the reference parameter file, you must include a `REFNAME` variable. The values of these will be compared against the name entered by the participant (on the join-the-survey page).

`last updated 30 June 2011`